Skip to content

Agent Mesh

api: make the agent a first-class policy principal

Antonio Ojeae673268f5e71
diff --git a/api/agent.go b/api/agent.go
new file mode 100644
index 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.go
new file mode 100644
index 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.go
index 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.go
index f11f1543..efe441bb 100644
--- a/api/policy.go
+++ b/api/policy.go
@@ -26,6 +26,7 @@ var (
FactGroup: {},
FactEmail: {},
FactNode: {},
+ FactAgent: {},
}
)