Agent Mesh
Go a2aa2a-protocolagent-meshagentic-aiinferencemcpmeshmesh-networknetwork-securitynetworking-aip2p-network
api: make the agent a first-class policy principal
Antonio Ojeae673268f5e71
diff --git a/api/agent.go b/api/agent.gonew file mode 100644index 00000000..20125996--- /dev/null+++ b/api/agent.go@@ -0,0 +1,118 @@+// 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"+ "strings"+)++// ============================================================================+// Agent Principals+// ============================================================================+//+// An agent is a mesh principal in its own right: policy is written about the+// agent, not about whichever node happens to be hosting it, and the identifier+// survives an agent being suspended on one host and resumed on another.+//+// Agent identifiers are a SAM convention, the way "user", "email" and "group"+// facts are. External identity systems are not expected to adopt it; a+// connector translates into it at admission, exactly as translateClaimsToFacts+// translates OIDC claims at node enrollment. That translation must be total,+// injective (or tenants collide), hierarchy-preserving (or wildcard policy+// stops being expressible and operators are forced back to enumeration), and+// auditable.+//+// spiffe://acme.example/prod/reviewer-7 -> agent:reviewer-7.prod.acme.example+//+// The dotted, most-specific-first shape is not cosmetic. BuildTargetDatalogFact+// compiles "*.acme.example" into a suffix fact that keeps the leading dot and+// "acme.*" into a prefix fact that keeps the trailing dot, so wildcards are+// already anchored on label boundaries: "evil-acme.example" cannot match+// "*.acme.example". A slash-separated identifier would need new fact kinds and+// new matching code, and would reintroduce the boundary bug this avoids.++const (+ // MaxAgentIDLen bounds an agent identifier, matching the DNS name limit it+ // is shaped after.+ MaxAgentIDLen = 253++ // MaxAgentLabelLen bounds one dot-separated label of an agent identifier.+ MaxAgentLabelLen = 63+)++// ValidateAgentID checks an agent identifier: the value part of an "agent:"+// member or target, without the prefix.+//+// The rules exist to keep prefix and suffix policy safe and unambiguous:+// lowercase because the shape is DNS-shaped and DNS is case-insensitive, so+// two identifiers differing only in case must not be two principals; at least+// two labels because the rightmost labels are the authority that keeps+// identifiers from colliding across tenants; and no wildcards, because a+// wildcard is a policy pattern and never an identity.+func ValidateAgentID(id string) error {+ if id == "" {+ return fmt.Errorf("agent id cannot be empty")+ }+ if len(id) > MaxAgentIDLen {+ return fmt.Errorf("agent id %q exceeds %d characters", id, MaxAgentIDLen)+ }+ if id != strings.ToLower(id) {+ return fmt.Errorf("agent id %q must be lowercase", id)+ }+ if strings.ContainsAny(id, "*:/ ") {+ return fmt.Errorf("agent id %q must not contain a wildcard, a scheme separator, a path or a space", id)+ }++ labels := strings.Split(id, ".")+ if len(labels) < 2 {+ return fmt.Errorf("agent id %q must be qualified by an authority, e.g. reviewer-7.prod.acme.example", id)+ }+ for _, label := range labels {+ if err := validateAgentLabel(label); err != nil {+ return fmt.Errorf("agent id %q: %w", id, err)+ }+ }+ return nil+}++// validateAgentLabel applies the same character rules as dnsNameRegex uses for+// service names, so an agent identifier and a service name are validated alike.+func validateAgentLabel(label string) error {+ if label == "" {+ return fmt.Errorf("empty label")+ }+ if len(label) > MaxAgentLabelLen {+ return fmt.Errorf("label %q exceeds %d characters", label, MaxAgentLabelLen)+ }+ for i, r := range label {+ switch {+ case r >= 'a' && r <= 'z', r >= '0' && r <= '9', r == '_':+ case r == '-' && i > 0:+ default:+ return fmt.Errorf("label %q contains an invalid character %q", label, r)+ }+ }+ return nil+}++// AgentMember renders an agent identifier as a policy member or target, the+// form used in allowed_targets and role bindings.+func AgentMember(id string) (string, error) {+ if err := ValidateAgentID(id); err != nil {+ return "", err+ }+ return FactAgent + ":" + id, nil+}diff --git a/api/agent_test.go b/api/agent_test.gonew file mode 100644index 00000000..3798eefd--- /dev/null+++ b/api/agent_test.go@@ -0,0 +1,112 @@+// 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 (+ "strings"+ "testing"++ "github.com/biscuit-auth/biscuit-go/v2"+)++func TestValidateAgentID(t *testing.T) {+ tests := []struct {+ name string+ id string+ wantErr bool+ }{+ {"fully qualified", "reviewer-7.prod.acme.example", false},+ {"two labels", "reviewer.acme", false},+ {"digits and underscores", "actor_1.ns0.acme.example", false},+ {"substrate actor host", "my-counter-1.demo.actors.resources.substrate.ate.dev", false},++ {"empty", "", true},+ {"single label has no authority", "reviewer", true},+ {"uppercase", "Reviewer.acme.example", true},+ {"wildcard is a pattern not an identity", "*.prod.acme.example", true},+ {"trailing wildcard", "acme.*", true},+ {"carries the prefix", "agent:reviewer.acme.example", true},+ {"contains a path", "acme.example/reviewer", true},+ {"contains a space", "reviewer 7.acme.example", true},+ {"empty label", "reviewer..acme", true},+ {"leading dot", ".acme.example", true},+ {"trailing dot", "reviewer.acme.", true},+ {"label starts with a hyphen", "-reviewer.acme.example", true},+ {"label too long", strings.Repeat("a", 64) + ".acme", true},+ {"id too long", strings.Repeat("a.", 130) + "acme", true},+ }++ for _, tc := range tests {+ t.Run(tc.name, func(t *testing.T) {+ err := ValidateAgentID(tc.id)+ if tc.wantErr && err == nil {+ t.Fatalf("ValidateAgentID(%q) = nil, want error", tc.id)+ }+ if !tc.wantErr && err != nil {+ t.Fatalf("ValidateAgentID(%q) returned error: %v", tc.id, err)+ }+ })+ }+}++func TestAgentMember(t *testing.T) {+ got, err := AgentMember("reviewer-7.prod.acme.example")+ if err != nil {+ t.Fatalf("AgentMember returned error: %v", err)+ }+ if want := "agent:reviewer-7.prod.acme.example"; got != want {+ t.Fatalf("AgentMember = %q, want %q", got, want)+ }++ if _, err := AgentMember("*.prod.acme.example"); err == nil {+ t.Fatal("AgentMember accepted a wildcard, want error")+ }+}++// TestAgentPolicyPatternsAreLabelAnchored is the reason agent identifiers are+// dot-separated: the existing target vocabulary compiles wildcards into facts+// that keep the anchoring dot, so a lookalike authority cannot match.+func TestAgentPolicyPatternsAreLabelAnchored(t *testing.T) {+ tests := []struct {+ name string+ pattern string+ wantFact string+ wantValue string+ }{+ {"suffix keeps the leading dot", "agent:*.prod.acme.example", FactGrantedTargetSuffix, ".prod.acme.example"},+ {"prefix keeps the trailing dot", "agent:acme.*", FactGrantedTargetPrefix, "acme."},+ {"exact", "agent:reviewer-7.prod.acme.example", FactGrantedTargetExact, "reviewer-7.prod.acme.example"},+ }++ for _, tc := range tests {+ t.Run(tc.name, func(t *testing.T) {+ fact := BuildTargetDatalogFact(tc.pattern)+ if fact.Name != tc.wantFact {+ t.Fatalf("BuildTargetDatalogFact(%q) produced %q, want %q", tc.pattern, fact.Name, tc.wantFact)+ }+ if len(fact.IDs) != 2 {+ t.Fatalf("BuildTargetDatalogFact(%q) produced %d terms, want 2", tc.pattern, len(fact.IDs))+ }+ gotFactName, ok := fact.IDs[0].(biscuit.String)+ if !ok || string(gotFactName) != FactAgent {+ t.Errorf("BuildTargetDatalogFact(%q) targets %v, want %q", tc.pattern, fact.IDs[0], FactAgent)+ }+ gotValue, ok := fact.IDs[1].(biscuit.String)+ if !ok || string(gotValue) != tc.wantValue {+ t.Errorf("BuildTargetDatalogFact(%q) value = %v, want %q", tc.pattern, fact.IDs[1], tc.wantValue)+ }+ })+ }+}diff --git a/api/datalog.go b/api/datalog.goindex 29888947..a105a954 100644--- a/api/datalog.go+++ b/api/datalog.go@@ -67,6 +67,14 @@ const (// Example Datalog: allow if node("12D3KooWP2G8nJCLASp1Kb4TmQS4wCpMH2vpSUz8ug8DYEJiuf1i")FactNode = "node"+ // FactAgent defines the agent on whose behalf a request is made. Unlike+ // FactNode it does not identify a host: it is appended to the token when an+ // agent is admitted, and the same identifier is asserted again wherever that+ // agent is next resumed. See api/agent.go for the identifier rules.+ // Contains: biscuit.String(agentID)+ // Example Datalog: allow if agent("reviewer-7.prod.acme.example")+ FactAgent = "agent"+// FactClientPeerID defines the client PeerID performing the request, used for replay defense.// Contains: biscuit.String(clientPeerID)// Example Datalog: check if client_peer_id($id), connection_peer_id($id)diff --git a/api/policy.go b/api/policy.goindex f11f1543..efe441bb 100644--- a/api/policy.go+++ b/api/policy.go@@ -26,6 +26,7 @@ var (FactGroup: {},FactEmail: {},FactNode: {},+ FactAgent: {},})