Skip to content

Agent Mesh

22.3 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 api

import (
	"fmt"
	"regexp"
	"strconv"
	"strings"
	"time"

	"github.com/libp2p/go-libp2p/core/protocol"
)

// ============================================================================
// Libp2p Protocol & Network Constants
// ============================================================================

const (
	// EnrollProtocolID is the libp2p protocol identifier for node enrollment.
	EnrollProtocolID protocol.ID = "/mesh/enroll/1.0.0"

	// MCPProtocolID is the libp2p protocol identifier for Model Context Protocol streams.
	MCPProtocolID protocol.ID = "/mesh/mcp/1.0.0"

	// AuthProtocolID is the libp2p protocol identifier for the zero-trust auth handshake.
	AuthProtocolID protocol.ID = "/mesh/auth/1.0.0"

	// GoAwayProtocolID is the libp2p protocol on which a router tells a member
	// it will no longer hold it; the stream carries one RouterGoAway.
	GoAwayProtocolID protocol.ID = "/mesh/goaway/1.0.0"

	// IngressProtocolID is the libp2p protocol identifier on which an enrolled
	// router forwards external HTTP ingress requests to a serving node.
	IngressProtocolID protocol.ID = "/mesh/ingress/1.0.0"

	// DHTProtocolPrefix namespaces the mesh's Kademlia DHT away from the
	// public IPFS one; the protocol every member and router registers for
	// it is DHTProtocolID.
	DHTProtocolPrefix protocol.ID = "/mesh"
	DHTProtocolID     protocol.ID = DHTProtocolPrefix + "/kad/1.0.0"

	// GossipEvents is the GossipSub topic used to broadcast mesh event updates (e.g., node bans).
	GossipEvents = "/mesh/events/v1"

	// GossipControlPlaneSync is the GossipSub topic used by the control plane to sync cluster state.
	GossipControlPlaneSync = "/mesh/control-plane/sync/v1"

	// DefaultAudience is the default audience string used in OIDC token validation.
	DefaultAudience = "agentmesh-audience"
)

// ============================================================================
// Token Lifespans & Session Constants
// ============================================================================

const (
	// BiscuitTokenTTL is the strict cryptographically enforced lifespan
	// of a minted Biscuit token (24 hours).
	// This is verified locally by each peer on every connection.
	BiscuitTokenTTL = 24 * time.Hour

	// OIDCSessionTTL is the default database-enforced lifespan of a node's OIDC
	// interactive enrollment session (90 days). After this period, the node
	// must re-authenticate with the OIDC provider to establish a new session.
	// Operators tune the cadence with the control plane's --oidc-session-ttl.
	OIDCSessionTTL = 90 * 24 * time.Hour

	// TokenRefreshCheckInterval is the frequency at which the node daemon and router check
	// if their current Biscuit token is close to expiration and needs to be proactively refreshed.
	TokenRefreshCheckInterval = 10 * time.Minute
)

// EnrollChallenge is the payload a bootstrap enrollee signs to prove
// possession of the private half of BootstrapEnrollRequest.public_key at
// POST /enroll, carried in that message's timestamp/challenge_signature
// fields. Binding the peer ID keeps a captured signature useless for any
// other peer; the domain prefix keeps it useless at any other endpoint.
func EnrollChallenge(peerID string, ts int64) []byte {
	return []byte("mesh:enroll:" + peerID + ":" + strconv.FormatInt(ts, 10))
}

// EnrollStatusChallenge is the payload a bootstrap enrollee signs to prove
// possession of the key it submitted at /enroll when polling
// GET /enroll/status. ts is unix milliseconds; the signature travels in the
// HeaderChallengeSignature header (unpadded base64url) alongside
// HeaderChallengeTimestamp.
func EnrollStatusChallenge(peerID string, ts int64) []byte {
	return []byte("mesh:enroll-status:" + peerID + ":" + strconv.FormatInt(ts, 10))
}

// RefreshChallenge is the payload an enrolled peer signs to prove possession
// of its identity key at POST /refresh, carried in TokenRefreshRequest's
// timestamp/challenge_signature fields alongside the expiring biscuit. Same
// shape as the other enrollment challenges: peer- and endpoint-bound, so a
// captured signature is useless anywhere else.
func RefreshChallenge(peerID string, ts int64) []byte {
	return []byte("mesh:refresh:" + peerID + ":" + strconv.FormatInt(ts, 10))
}

// RegisterChallenge is the payload an OIDC enrollee signs to prove possession
// of EnrollRequest.public_key at POST /register, carried in that message's
// timestamp/challenge_signature fields. The JWT says who is asking; this says
// they hold the key they are binding.
func RegisterChallenge(peerID string, ts int64) []byte {
	return []byte("mesh:register:" + peerID + ":" + strconv.FormatInt(ts, 10))
}

// RouterLeaseChallenge is the payload a router signs with its enrolled key at
// POST /routers/lease, carried in RouterLeaseRequest's
// timestamp/challenge_signature fields. The router's biscuit is not proof on
// its own: routers send it to every peer they authenticate.
func RouterLeaseChallenge(peerID string, ts int64) []byte {
	return []byte("mesh:routers-lease:" + peerID + ":" + strconv.FormatInt(ts, 10))
}

// TokenExchangeChallenge is the payload an enrolled agentmesh-node signs with its
// identity key at POST /token/exchange to prove possession of the channel key
// that will carry the minted Delegated Session Biscuit.
func TokenExchangeChallenge(peerID string, ts int64) []byte {
	return []byte("mesh:token-exchange:" + peerID + ":" + strconv.FormatInt(ts, 10))
}

// STSTokenChallenge is the payload an enrolled egress agentmesh-node signs with its
// identity key at POST /sts/token when asking the control plane to mint an
// ES256 border JWT for an outbound destination.
func STSTokenChallenge(peerID string, ts int64) []byte {
	return []byte("mesh:sts-token:" + peerID + ":" + strconv.FormatInt(ts, 10))
}

// PoliciesChallenge is the payload an enrolled peer signs with its identity
// key at GET /policies in the HeaderChallengeTimestamp and
// HeaderChallengeSignature headers.
func PoliciesChallenge(peerID string, ts int64) []byte {
	return []byte("mesh:policies:" + peerID + ":" + strconv.FormatInt(ts, 10))
}

// EgressChallenge is the payload an enrolled peer signs with its identity key
// at GET /egress in the HeaderChallengeTimestamp and HeaderChallengeSignature
// headers.
func EgressChallenge(peerID string, ts int64) []byte {
	return []byte("mesh:egress:" + peerID + ":" + strconv.FormatInt(ts, 10))
}

// RevocationsChallenge is the payload an enrolled peer signs with its identity
// key at GET /revocations in the HeaderChallengeTimestamp and
// HeaderChallengeSignature headers.
func RevocationsChallenge(peerID string, ts int64) []byte {
	return []byte("mesh:revocations:" + peerID + ":" + strconv.FormatInt(ts, 10))
}

// NodesCatalogChallenge is the payload an enrolled node signs with its
// identity key at POST /nodes/catalog in the HeaderChallengeTimestamp and
// HeaderChallengeSignature headers.
func NodesCatalogChallenge(peerID string, ts int64) []byte {
	return []byte("mesh:nodes-catalog:" + peerID + ":" + strconv.FormatInt(ts, 10))
}

// ErrStaleChallengeTimestampMessage is the stable substring returned in a 401
// response body when a signed challenge timestamp is outside the control
// plane's freshness window. Clients match this message to recompute
// challenge_unix_ms from the response's Date header and retry once.
const ErrStaleChallengeTimestampMessage = "stale or invalid challenge timestamp"

// ============================================================================
// OAuth 2.1 & RFC 8693 Token Exchange Constants
// ============================================================================

const (
	// GrantTypeTokenExchange is the RFC 8693 OAuth 2.0 Token Exchange grant type URI.
	GrantTypeTokenExchange = "urn:ietf:params:oauth:grant-type:token-exchange"

	// GrantTypeAuthorizationCode is the standard OAuth 2.1 authorization_code grant type.
	GrantTypeAuthorizationCode = "authorization_code"

	// GrantTypeClientCredentials is the RFC 6749 client_credentials grant type.
	GrantTypeClientCredentials = "client_credentials"

	// GrantTypeJWTBearer is the RFC 7523 section 2.1 JWT authorization grant type URI.
	GrantTypeJWTBearer = "urn:ietf:params:oauth:grant-type:jwt-bearer"

	// ClientAssertionTypeJWTBearer is the RFC 7523 section 2.2 client assertion type URI.
	ClientAssertionTypeJWTBearer = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"

	// ClientAssertionTypeJWTSPIFFE is the client assertion type URI for a SPIFFE
	// JWT-SVID (draft-ietf-oauth-spiffe-client-auth).
	ClientAssertionTypeJWTSPIFFE = "urn:ietf:params:oauth:client-assertion-type:jwt-spiffe"

	// TokenTypeBiscuit is the token type URI identifying a Agent Mesh Biscuit token in RFC 8693 exchanges.
	TokenTypeBiscuit = "urn:agentmesh:params:oauth:token-type:biscuit"

	// TokenTypeJWT is the RFC 8693 JWT token type URI.
	TokenTypeJWT = "urn:ietf:params:oauth:token-type:jwt"

	// TokenTypeIDToken is the RFC 8693 OIDC ID token type URI.
	TokenTypeIDToken = "urn:ietf:params:oauth:token-type:id_token"

	// TokenTypeAccessToken is the RFC 8693 OAuth access token type URI.
	TokenTypeAccessToken = "urn:ietf:params:oauth:token-type:access_token"
)

// OAuthAuthorizationServerMetadata is the RFC 8414 document a token endpoint
// serves at /.well-known/oauth-authorization-server. Only the fields Agent Mesh
// populates are present; omitted RFC 8414 fields are optional there too.
type OAuthAuthorizationServerMetadata struct {
	Issuer                                 string   `json:"issuer"`
	AuthorizationEndpoint                  string   `json:"authorization_endpoint,omitempty"`
	TokenEndpoint                          string   `json:"token_endpoint"`
	RevocationEndpoint                     string   `json:"revocation_endpoint,omitempty"`
	JWKSURI                                string   `json:"jwks_uri,omitempty"`
	ResponseTypesSupported                 []string `json:"response_types_supported"`
	GrantTypesSupported                    []string `json:"grant_types_supported,omitempty"`
	TokenEndpointAuthMethodsSupported      []string `json:"token_endpoint_auth_methods_supported,omitempty"`
	RevocationEndpointAuthMethodsSupported []string `json:"revocation_endpoint_auth_methods_supported,omitempty"`
	CodeChallengeMethodsSupported          []string `json:"code_challenge_methods_supported,omitempty"`
}

// OAuthProtectedResourceMetadata is the RFC 9728 document a resource server
// serves at /.well-known/oauth-protected-resource.
type OAuthProtectedResourceMetadata struct {
	Resource               string   `json:"resource"`
	AuthorizationServers   []string `json:"authorization_servers,omitempty"`
	BearerMethodsSupported []string `json:"bearer_methods_supported,omitempty"`
	ScopesSupported        []string `json:"scopes_supported,omitempty"`
}

// ============================================================================
// Agent Mesh Custom HTTP Headers
// ============================================================================

const (
	// HeaderMeshBiscuit is the custom HTTP header used to carry the base64-encoded
	// Biscuit token containing the node's identity credentials when forwarding requests
	// over libp2p HTTP between nodes in the mesh.
	//
	// This header is internal to the Agent Mesh datapath and is stripped before requests
	// are forwarded to backend services.
	HeaderMeshBiscuit = "X-Mesh-Biscuit"

	// HeaderChallengeTimestamp and HeaderChallengeSignature carry the signed
	// freshness challenge on GET /enroll/status, GET /policies, GET /egress,
	// GET /revocations, and POST /nodes/catalog: unix milliseconds and an
	// unpadded base64url signature over the endpoint's challenge payload.
	// Headers rather than query parameters, so the signature never lands in
	// access logs, where it would be replayable for its freshness window.
	HeaderChallengeTimestamp = "X-Mesh-Challenge-Ts"
	HeaderChallengeSignature = "X-Mesh-Challenge-Sig"

	// HeaderPeerID carries the authenticated libp2p peer ID of the caller.
	// The mesh ingress handler stamps it after authorization succeeds,
	// overwriting any inbound value, so backend services get verified caller
	// attribution without parsing biscuits. The inference facade sets it the
	// same way for locally served requests.
	HeaderPeerID = "X-Peer-Id"

	// HeaderMeshAuthentication is the custom HTTP header used to authenticate a local
	// process to this node's sidecar API (the shared secret configured via
	// "--api-token-path" or the AGENTMESH_API_TOKEN environment variable). Using a
	// Agent Mesh-specific header name — instead of the standard
	// "Authorization" header — leaves "Authorization" free to always mean what
	// every HTTP client expects: the credential for the destination being called.
	// The sidecar strips this header before forwarding any request off-node, so
	// it never leaks to a remote peer or backend service.
	//
	// For compatibility with MCP clients that only support a plain "Authorization"
	// header, purely-local endpoints (that never forward it anywhere) also accept
	// "Authorization" as an alias. The egress/inference proxy does NOT: there,
	// "Authorization" is reserved exclusively for the destination's credential.
	HeaderMeshAuthentication = "X-Mesh-Authentication"

	// HeaderMeshNoTrailingSlash is the custom HTTP header set by the ingress handler
	// to indicate that the original request had no trailing slash.
	//
	// This helps backward-compatibility with services that strictly distinguish
	// between a root path "/" and an empty path "".
	HeaderMeshNoTrailingSlash = "X-Mesh-No-Trailing-Slash"

	// HeaderMeshRequiredLabels constrains an inference request on the sidecar's
	// OpenAI-compatible endpoints (/v1/*) to providers attested with every
	// pair of a comma-separated list of "key=value" label requirements (see
	// api/labels.go and LabelCheck); invalid entries are rejected with HTTP
	// 400. It can only narrow what mesh policy allows, never widen it. Absent
	// means any provider permitted by policy.
	//
	// Reserved as part of the sidecar contract; enforced by the provider
	// scorer. Label declarations are routing hints until attested via the
	// node's Biscuit (see api/labels.go).
	HeaderMeshRequiredLabels = "X-Mesh-Required-Labels"

	// HeaderMeshPrincipal, HeaderMeshRoles, HeaderMeshTask, and HeaderMeshTaskID carry
	// verified caller attribution injected by ext_authz or forwarded to an
	// operator inspection chain when forward_context is enabled.
	HeaderMeshPrincipal     = "X-Mesh-Principal"
	HeaderMeshRoles         = "X-Mesh-Roles"
	HeaderMeshTask          = "X-Mesh-Task"
	HeaderMeshTaskID        = "X-Mesh-Task-Id"
	HeaderMeshTargetService = "X-Mesh-Target-Service"

	// HeaderMeshIngress marks a request delivered over router external ingress
	// ("edge" or "passthrough"). Inbound values from external callers are
	// stripped at both the router and the serving node.
	HeaderMeshIngress = "X-Mesh-Ingress"

	// HeaderMeshIngressCallerBiscuit carries the base64-encoded caller Biscuit
	// from an enrolled router to the serving node over IngressProtocolID so the
	// node can re-verify Datalog policy, local attenuation, TAR, and allow-lists
	// end to end. Stripped before forwarding to the backend service.
	HeaderMeshIngressCallerBiscuit = "X-Mesh-Ingress-Caller-Biscuit"
)

// ============================================================================
// Service Classification & Namespaces
// ============================================================================

const (
	// SystemNamespace is the namespace reserved for built-in mesh services and protocols.
	SystemNamespace = "mesh:system"

	// CatalogTarget is the special system service name used to retrieve tool catalogs.
	// In policy rules, it must be referred to explicitly as: system://mesh.catalog
	CatalogTarget = "mesh.catalog"

	// MCPServicePrefix is the scheme prefix for Model Context Protocol services.
	// Fully qualified MCP services use the URI format: mcp://<service-name>
	MCPServicePrefix = "mcp://"

	// InferenceServicePrefix is the scheme prefix for LLM Inference services.
	// Fully qualified inference services use the URI format: inference://<service-name>
	InferenceServicePrefix = "inference://"

	// EgressServicePrefix is the scheme prefix for destinations outside the
	// mesh, served by a node that enforces policy on them. The name is the
	// destination hostname: egress://api.github.com
	EgressServicePrefix = "egress://"
)

// ============================================================================
// Protocol Types & String Mappings
// ============================================================================

const (
	// ServiceTypeStringMCP is the string identifier for MCP services.
	ServiceTypeStringMCP = "mcp"

	// ServiceTypeStringInference is the string identifier for Inference services.
	ServiceTypeStringInference = "inference"

	// ServiceTypeStringA2A is the string identifier for A2A (Agent2Agent) services.
	ServiceTypeStringA2A = "a2a"

	// ServiceTypeStringEgress is the string identifier for egress destinations.
	ServiceTypeStringEgress = "egress"
)

// ParseServiceType converts a string identifier (e.g. from JSON or REST) to the ServiceType protobuf enum.
func ParseServiceType(s string) (ServiceType, error) {
	switch strings.ToLower(s) {
	case ServiceTypeStringMCP:
		return ServiceType_SERVICE_TYPE_MCP, nil
	case ServiceTypeStringInference:
		return ServiceType_SERVICE_TYPE_INFERENCE, nil
	case ServiceTypeStringA2A:
		return ServiceType_SERVICE_TYPE_A2A, nil
	case ServiceTypeStringEgress:
		return ServiceType_SERVICE_TYPE_EGRESS, nil
	default:
		return ServiceType_SERVICE_TYPE_UNSPECIFIED, fmt.Errorf("invalid service type: %s", s)
	}
}

// ServiceTypeToString converts a ServiceType protobuf enum back to its standard string identifier.
func ServiceTypeToString(t ServiceType) (string, error) {
	switch t {
	case ServiceType_SERVICE_TYPE_MCP:
		return ServiceTypeStringMCP, nil
	case ServiceType_SERVICE_TYPE_INFERENCE:
		return ServiceTypeStringInference, nil
	case ServiceType_SERVICE_TYPE_A2A:
		return ServiceTypeStringA2A, nil
	case ServiceType_SERVICE_TYPE_EGRESS:
		return ServiceTypeStringEgress, nil
	default:
		return "", fmt.Errorf("invalid or unspecified service type")
	}
}

// ============================================================================
// Parsing & Routing Utilities
// ============================================================================

var (
	// rfc3986URIRegex is the exact regular expression provided by RFC 3986 Appendix B
	// for breaking down a well-formed URI reference into its components.
	// Reference: https://tools.ietf.org/html/rfc3986#appendix-B
	//
	// Breaking down the regex:
	//   ^(([^:/?#]+):)?   - Group 1 & 2: Scheme (optional, e.g. "mcp:")
	//   (//([^/?#]*))?    - Group 3 & 4: Authority (optional, e.g. "//my-service")
	//   ([^?#]*)          - Group 5: Path
	//   (\?([^#]*))?      - Group 6 & 7: Query (optional)
	//   (#(.*))?          - Group 8 & 9: Fragment (optional)
	rfc3986URIRegex = regexp.MustCompile(`^(([^:/?#]+):)?(//([^/?#]*))?([^?#]*)(\?([^#]*))?(#(.*))?`)

	// dnsNameRegex is adapted from govalidator's DNSName pattern.
	// Reference: https://github.com/asaskevich/govalidator/blob/3dd3875e2b081a20d6eed935913a482fea14ecd0/patterns.go#L29
	// It is adapted to allow underscores and asterisks (wildcards).
	// The asterisk '*' can only be at the very beginning (e.g., "*.example.com") or at the very end (e.g., "example.*").
	dnsNameRegex = regexp.MustCompile(`^(\*\.)?([a-zA-Z0-9_]{1}[a-zA-Z0-9_-]{0,62}){1}(\.[a-zA-Z0-9_]{1}[a-zA-Z0-9_-]{0,62})*(\.\*)?[\._]?$`)
)

// ParseServiceTarget parses a service target string into its type (scheme) and name components.
//
// Expected formats:
//   - Hierarchical service URIs: "scheme://name" (e.g., "mcp://my_service") or "scheme://name/path" (e.g., "mcp://my_service/tool").
//   - Target facts: "fact:value" (e.g., "group:backend" or "user:bob").
//   - Wildcards: "*" (maps type to "*" and name to "*").
//
// If no scheme/colon is present, it returns an empty string for the type and the full target as the name.
// No fallback namespace is applied; callers must be explicit.
func ParseServiceTarget(target string) (svcType, svcName string) {
	if target == "*" {
		return "*", "*"
	}

	if idx := strings.Index(target, "://"); idx >= 0 && !strings.Contains(target[:idx], ":") {
		matches := rfc3986URIRegex.FindStringSubmatch(target)
		if len(matches) < 6 {
			return "", target
		}
		scheme := matches[2]
		hasAuthority := matches[3] != ""
		authority := matches[4]
		path := matches[5]

		if scheme == "" || !hasAuthority {
			return "", target
		}
		name := authority
		if path != "" {
			name = authority + path
		}
		return scheme, name
	}

	parts := strings.SplitN(target, ":", 2)
	if len(parts) == 2 {
		return parts[0], parts[1]
	}
	return "", target
}

// SplitToolName splits a fully qualified MCP tool name into its target service URI
// and the original tool name.
//
// Expected format: "scheme://service/tool" (e.g., "mcp://my-service/my-tool").
// If the input is empty or invalid, it returns an error. No default fallback is applied.
func SplitToolName(toolName string) (targetService, originalToolName string, err error) {
	if toolName == "" {
		return "", "", fmt.Errorf("tool name cannot be empty")
	}

	matches := rfc3986URIRegex.FindStringSubmatch(toolName)
	if len(matches) < 6 {
		return "", "", fmt.Errorf("invalid namespaced tool name %q: must follow explicit URI format 'scheme://service/tool'", toolName)
	}

	scheme := matches[2]
	hasAuthority := matches[3] != ""
	authority := matches[4]
	path := matches[5]

	if scheme == "" || !hasAuthority || authority == "" || path == "" || path == "/" {
		return "", "", fmt.Errorf("invalid namespaced tool name %q: must follow explicit URI format 'scheme://service/tool'", toolName)
	}

	// Reject query parameters or fragments in the tool name
	if matches[6] != "" || matches[8] != "" {
		return "", "", fmt.Errorf("invalid namespaced tool name %q: queries and fragments are not allowed", toolName)
	}

	targetService = scheme + "://" + authority
	originalToolName = strings.TrimPrefix(path, "/")
	return targetService, originalToolName, nil
}