Agent Mesh
Go a2aa2a-protocolagent-meshagentic-aiinferencemcpmeshmesh-networknetwork-securitynetworking-aip2p-network
// 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"
"net/url"
"regexp"
"strings"
"github.com/eclipse-biscuit/biscuit-go/v2"
"google.golang.org/protobuf/proto"
)
// credentialNameSyntax bounds a credential name to one safe file name: the
// serving node resolves it under its secrets directory, so it must not be
// able to name a path.
var credentialNameSyntax = regexp.MustCompile(`^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,63}$`)
// EgressStaticSecret returns the static secret file name configured on d,
// whether specified via broker.static_secret or the shorthand credential field.
func EgressStaticSecret(d *EgressDestination) string {
if s := d.GetBroker().GetStaticSecret(); s != "" {
return s
}
return d.GetCredential()
}
// ValidateEgressDestination checks one PolicyConfig.egress entry. roleNames
// are the roles the same document defines, so served_by can be checked
// against them; a label entry is checked for form only.
func ValidateEgressDestination(d *EgressDestination, roleNames map[string]bool) error {
if d == nil {
return fmt.Errorf("egress entry is nil")
}
if err := ValidateEgressName(d.GetName()); err != nil {
return err
}
if d.GetTargetUrl() != "" {
if err := validateEgressTargetURL(d.GetTargetUrl()); err != nil {
return fmt.Errorf("egress %q: %w", d.GetName(), err)
}
}
if d.GetCredential() != "" && !credentialNameSyntax.MatchString(d.GetCredential()) {
return fmt.Errorf("egress %q: credential %q must be a name of 1-64 chars of [a-zA-Z0-9_.-], not a path or a value", d.GetName(), d.GetCredential())
}
if b := d.GetBroker(); b != nil {
if d.GetCredential() != "" && (b.GetStaticSecret() == "" || b.GetStaticSecret() != d.GetCredential()) {
return fmt.Errorf("egress %q: cannot set both credential and broker", d.GetName())
}
switch kind := b.GetKind().(type) {
case *CredentialBroker_StaticSecret:
if kind.StaticSecret != "" && !credentialNameSyntax.MatchString(kind.StaticSecret) {
return fmt.Errorf("egress %q: broker.static_secret %q must be a name of 1-64 chars of [a-zA-Z0-9_.-], not a path or a value", d.GetName(), kind.StaticSecret)
}
case *CredentialBroker_OidcFederation:
if kind.OidcFederation == nil || strings.TrimSpace(kind.OidcFederation.GetAudience()) == "" {
return fmt.Errorf("egress %q: broker.oidc_federation.audience is required", d.GetName())
}
if ep := kind.OidcFederation.GetTokenEndpoint(); ep != "" {
if err := validateEgressTargetURL(ep); err != nil {
return fmt.Errorf("egress %q: broker.oidc_federation.token_endpoint: %w", d.GetName(), err)
}
}
case *CredentialBroker_AwsAssumeRole:
if kind.AwsAssumeRole == nil || strings.TrimSpace(kind.AwsAssumeRole.GetRoleArn()) == "" {
return fmt.Errorf("egress %q: broker.aws_assume_role.role_arn is required", d.GetName())
}
case *CredentialBroker_PlatformIdentity:
// PlatformIdentity uses node metadata server; scopes are optional.
}
}
if d.GetMode() == EgressMode_EGRESS_MODE_TCP && len(d.GetPorts()) == 0 {
return fmt.Errorf("egress %q: mode EGRESS_MODE_TCP requires at least one port in ports", d.GetName())
}
for _, p := range d.GetPorts() {
if p == 0 || p > 65535 {
return fmt.Errorf("egress %q: port %d must be in 1..65535", d.GetName(), p)
}
}
for i, ins := range d.GetInspection().GetInspectors() {
if ins == nil {
return fmt.Errorf("egress %q: inspector[%d] is nil", d.GetName(), i)
}
switch kind := ins.GetKind().(type) {
case *Inspector_ModelArmor:
if kind.ModelArmor == nil || strings.TrimSpace(kind.ModelArmor.GetTemplate()) == "" {
return fmt.Errorf("egress %q: inspector[%d].model_armor.template is required", d.GetName(), i)
}
case *Inspector_ExtProc:
if kind.ExtProc == nil || strings.TrimSpace(kind.ExtProc.GetTarget()) == "" {
return fmt.Errorf("egress %q: inspector[%d].ext_proc.target is required", d.GetName(), i)
}
if ca := kind.ExtProc.GetCa(); ca != "" && !credentialNameSyntax.MatchString(ca) {
return fmt.Errorf("egress %q: inspector[%d].ext_proc.ca %q must be a file name in the secrets directory", d.GetName(), i, ca)
}
if cc := kind.ExtProc.GetClientCertificate(); cc != "" && !credentialNameSyntax.MatchString(cc) {
return fmt.Errorf("egress %q: inspector[%d].ext_proc.client_certificate %q must be a file name in the secrets directory", d.GetName(), i, cc)
}
default:
return fmt.Errorf("egress %q: inspector[%d] must specify model_armor or ext_proc", d.GetName(), i)
}
}
if len(d.GetServedBy()) == 0 {
return fmt.Errorf("egress %q: served_by must select at least one role or label", d.GetName())
}
for _, sel := range d.GetServedBy() {
if key, value, isLabel := strings.Cut(sel, "="); isLabel {
if err := ValidateLabelKey(key); err != nil {
return fmt.Errorf("egress %q: served_by %q: %w", d.GetName(), sel, err)
}
if err := ValidateLabelValue(value); err != nil {
return fmt.Errorf("egress %q: served_by %q: %w", d.GetName(), sel, err)
}
continue
}
if !roleNames[sel] {
return fmt.Errorf("egress %q: served_by %q is neither a role in this policy nor a key=value label", d.GetName(), sel)
}
}
return nil
}
// ValidateEgressName checks a destination name: a lowercase hostname with no
// wildcard, port or path. It is the service name of egress://<name>, so it
// must also be valid there.
func ValidateEgressName(name string) error {
if name == "" {
return fmt.Errorf("egress entry has no name")
}
if name != NormalizeMeshHost(name) {
return fmt.Errorf("egress name %q must be lowercase with no trailing dot", name)
}
if strings.ContainsAny(name, "*:/") {
return fmt.Errorf("egress name %q must be one hostname: no wildcard, port or path", name)
}
if err := ValidateServiceFormat(EgressServicePrefix + name); err != nil {
return err
}
return nil
}
// ValidateEgressServicePattern checks an egress entry of allowed_services,
// allowed_publish or http.service. The generic service validator accepts a
// path and any case, which for the other types name a service that may
// exist; an egress name is a hostname, matched against a lowercase
// destination name, so a path, a port, uppercase or a trailing dot would
// compile to a grant that matches nothing. Entries of other types pass
// through unchanged.
func ValidateEgressServicePattern(svc string) error {
svcType, name := ParseServiceTarget(svc)
if svcType != ServiceTypeStringEgress {
return nil
}
if err := ValidateServiceFormat(svc); err != nil {
return err
}
if name == "*" {
return nil
}
if strings.ContainsAny(name, ":/") {
return fmt.Errorf("invalid egress pattern %q: a destination is a hostname, without a scheme, a port or a path (write the path in the role's http entry)", svc)
}
if name != NormalizeMeshHost(name) {
return fmt.Errorf("invalid egress pattern %q: destination names are lowercase with no trailing dot", svc)
}
return nil
}
// validateEgressTargetURL accepts an http or https URL with a host and no
// credential; a credential is named by EgressDestination.credential and
// resolved on the serving node.
func validateEgressTargetURL(raw string) error {
u, err := url.Parse(raw)
if err != nil {
return fmt.Errorf("invalid target_url")
}
if u.Scheme != "http" && u.Scheme != "https" {
return fmt.Errorf("target_url %q must use http or https", raw)
}
if u.Hostname() == "" {
return fmt.Errorf("target_url %q has no host", raw)
}
if u.User != nil {
return fmt.Errorf("target_url must not carry a credential; name one in credential instead")
}
if u.RawQuery != "" || u.Fragment != "" {
return fmt.Errorf("target_url %q must not carry a query or a fragment", raw)
}
return nil
}
// EgressTargetURL is where the serving node forwards requests for d:
// target_url when set, otherwise https on the destination name.
func EgressTargetURL(d *EgressDestination) string {
if d.GetTargetUrl() != "" {
return d.GetTargetUrl()
}
return "https://" + d.GetName()
}
// EgressServedBy reports whether a node with these roles and labels is
// selected to serve d.
func EgressServedBy(d *EgressDestination, roles []string, labels map[string]string) bool {
for _, sel := range d.GetServedBy() {
if key, value, isLabel := strings.Cut(sel, "="); isLabel {
if labels[key] == value {
return true
}
continue
}
for _, r := range roles {
if r == sel {
return true
}
}
}
return false
}
// WithEgressPublish returns policyRoles with the egress destinations a node
// with these roles and labels serves added to what it may publish: served_by
// is who may serve a destination, and the record the node announces for it
// needs the grant like any other. The role entries are copied, never
// changed in place; a role the policy does not define gets an entry that
// grants publishing alone.
func WithEgressPublish(policyRoles []*PolicyRole, egress []*EgressDestination, roles []string, labels map[string]string) []*PolicyRole {
var served []string
for _, d := range egress {
if d == nil || ValidateEgressName(d.GetName()) != nil {
continue
}
if EgressServedBy(d, roles, labels) {
served = append(served, ServiceTypeStringEgress+"://"+d.GetName())
}
}
if len(served) == 0 || len(roles) == 0 {
return policyRoles
}
out := make([]*PolicyRole, 0, len(policyRoles)+1)
found := false
for _, pr := range policyRoles {
if pr != nil && pr.GetName() == roles[0] {
cp := proto.Clone(pr).(*PolicyRole)
cp.AllowedPublish = append(cp.AllowedPublish, served...)
out = append(out, cp)
found = true
continue
}
out = append(out, pr)
}
if !found {
out = append(out, &PolicyRole{Name: roles[0], AllowedPublish: served})
}
return out
}
// BuildEgressServingRules grants each destination to the nodes that serve it:
// granted_service_exact("egress", name) and granted_publish_exact("egress", name)
// <- role(r) or <- label(k, v) for every served_by entry. The serving node
// evaluates its own credential when a local client asks for the destination,
// and the router and the callers evaluate it when the node publishes, so
// both grants have to reach them; the rules travel with the mesh policy like
// every other grant.
func BuildEgressServingRules(egress []*EgressDestination) []PolicyRule {
var rules []PolicyRule
for _, d := range egress {
if d == nil || ValidateEgressName(d.GetName()) != nil {
continue
}
destination := []biscuit.Term{biscuit.String(ServiceTypeStringEgress), biscuit.String(d.GetName())}
heads := []biscuit.Predicate{
{Name: FactGrantedServiceExact, IDs: destination},
{Name: FactGrantedPublishExact, IDs: destination},
}
for _, sel := range d.GetServedBy() {
var body biscuit.Predicate
if key, value, isLabel := strings.Cut(sel, "="); isLabel {
if ValidateLabelKey(key) != nil || ValidateLabelValue(value) != nil {
continue
}
body = biscuit.Predicate{Name: FactLabel, IDs: []biscuit.Term{biscuit.String(key), biscuit.String(value)}}
} else {
if ValidateRoleName(sel) != nil {
continue
}
body = biscuit.Predicate{Name: FactRole, IDs: []biscuit.Term{biscuit.String(sel)}}
}
for _, head := range heads {
r := biscuit.Rule{Head: head, Body: []biscuit.Predicate{body}}
rules = append(rules, PolicyRule{Rule: r, Text: renderRule(r)})
}
}
}
return rules
}