Agent Mesh
Go a2aa2a-protocolagent-meshagentic-aiinferencemcpmeshmesh-networknetwork-securitynetworking-aip2p-network
api: project mesh service names into DNS-shaped hostnames
Antonio Ojea00bc33e597f0
diff --git a/api/names.go b/api/names.gonew file mode 100644index 00000000..43f9b3a3--- /dev/null+++ b/api/names.go@@ -0,0 +1,156 @@+// 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"+)++// ============================================================================+// Sandbox Mesh Names+// ============================================================================+//+// Agents run inside sandboxes (Firecracker microVMs, network=none containers)+// and reach the mesh by connecting to a *name*, exactly as they would reach the+// public internet. This file defines the one projection of the mesh service+// namespace into DNS-shaped names, so that a hostname seen on the sandbox+// boundary and a service URI seen by the policy engine are the same identity+// written two ways:+//+// inference://openrouter <-> openrouter.inference.sam.alt+// mcp://code-reviewer <-> code-reviewer.mcp.sam.alt+//+// The URI form (see MCPServicePrefix / InferenceServicePrefix in network.go) is+// canonical: it is what the control plane authorizes in allowed_services and+// what lands in the Biscuit service() fact. The hostname form exists only so+// unmodified agents can use an unmodified HTTP client. Never introduce a+// routing decision that can be expressed in one form but not the other.++const (+ // MeshZone is the DNS suffix under which mesh services are addressed from+ // inside a sandbox.+ //+ // ".alt" is the pseudo-top-level domain reserved by RFC 9476 for namespaces+ // that are explicitly NOT resolved through the DNS. That is precisely this+ // case: these names are resolved by the mesh (service discovery over+ // libp2p), never by a resolver. Using it guarantees the zone can never+ // collide with a delegated gTLD, and guarantees a name that leaks out of a+ // sandbox fails closed instead of resolving to somebody else's host.+ MeshZone = "sam.alt"++ // LocalNodeHost is the reserved name for the agent's own gateway: the+ // sidecar API of the sam-node it is attached to. Connecting here is+ // equivalent to talking to the local sidecar over its Unix socket, so+ // /v1/*, /mcp and /sam/* behave exactly as documented for that API.+ LocalNodeHost = "node." + MeshZone+)++// meshZoneSuffix is the dotted form used for suffix matching.+const meshZoneSuffix = "." + MeshZone++// NormalizeMeshHost canonicalizes a hostname taken off the sandbox boundary: it+// drops a trailing root dot and lowercases the name. DNS names are+// case-insensitive, so a mesh name only ever addresses a lowercase service+// name; services registered with uppercase characters are reachable by URI but+// not by hostname.+func NormalizeMeshHost(host string) string {+ return strings.ToLower(strings.TrimSuffix(strings.TrimSpace(host), "."))+}++// IsMeshHost reports whether host falls inside the mesh zone. It does not+// validate the name beyond the suffix: use ParseMeshHost for that.+func IsMeshHost(host string) bool {+ h := NormalizeMeshHost(host)+ return h == MeshZone || strings.HasSuffix(h, meshZoneSuffix)+}++// IsLocalNodeHost reports whether host addresses the local sidecar.+func IsLocalNodeHost(host string) bool {+ return NormalizeMeshHost(host) == LocalNodeHost+}++// ParseMeshHost translates a mesh hostname into its canonical service URI.+//+// openrouter.inference.sam.alt -> inference://openrouter+// code-reviewer.mcp.sam.alt -> mcp://code-reviewer+//+// The service type is the label immediately left of the zone; everything to its+// left is the service name, which may itself contain dots (service names are+// validated as DNS names, not as single labels). LocalNodeHost is not a service+// and is rejected here; callers must test it with IsLocalNodeHost first.+//+// Names are not resolved to a provider: which peer serves the returned URI is a+// discovery decision, and deliberately not encoded in the name. If pinning to+// one provider is ever needed, the natural extension is a longer form carrying+// the peer — mirroring the internal libp2p://<peer>/<type>/<name> URL — but it+// requires settling on a DNS-safe peer encoding first, because a base58 peer ID+// is case-sensitive and DNS labels are not (IPFS solves the same problem in+// subdomain gateways by using lowercase base36 CIDs).+func ParseMeshHost(host string) (serviceURI string, err error) {+ h := NormalizeMeshHost(host)+ if h == "" {+ return "", fmt.Errorf("empty mesh host")+ }+ // A hostname carries neither a port nor a path: stripping those is the+ // caller's job, and anything else here means a malformed request that must+ // fail closed rather than be coerced into a service URI.+ if strings.ContainsAny(h, ":/") {+ return "", fmt.Errorf("mesh host %q must not contain a port or a path", host)+ }+ if h == LocalNodeHost {+ return "", fmt.Errorf("%q is the local node, not a mesh service", host)+ }+ rest, found := strings.CutSuffix(h, meshZoneSuffix)+ if !found || rest == "" {+ return "", fmt.Errorf("host %q is not in the mesh zone %q", host, MeshZone)+ }++ dot := strings.LastIndex(rest, ".")+ if dot <= 0 || dot == len(rest)-1 {+ return "", fmt.Errorf("mesh host %q must be <service>.<type>.%s", host, MeshZone)+ }+ name, typeStr := rest[:dot], rest[dot+1:]++ if _, err := ParseServiceType(typeStr); err != nil {+ return "", fmt.Errorf("mesh host %q: %w", host, err)+ }++ uri := typeStr + "://" + name+ if err := ValidateServiceFormat(uri); err != nil {+ return "", fmt.Errorf("mesh host %q: %w", host, err)+ }+ return uri, nil+}++// MeshHost is the inverse of ParseMeshHost: it renders the hostname a sandboxed+// agent should connect to in order to reach the given service.+func MeshHost(t ServiceType, serviceName string) (string, error) {+ typeStr, err := ServiceTypeToString(t)+ if err != nil {+ return "", err+ }+ if serviceName == "" {+ return "", fmt.Errorf("service name cannot be empty")+ }+ if serviceName != NormalizeMeshHost(serviceName) {+ return "", fmt.Errorf("service name %q is not addressable as a mesh host: it must be lowercase", serviceName)+ }+ host := serviceName + "." + typeStr + meshZoneSuffix+ if _, err := ParseMeshHost(host); err != nil {+ return "", err+ }+ return host, nil+}diff --git a/api/names_test.go b/api/names_test.gonew file mode 100644index 00000000..da9e51e2--- /dev/null+++ b/api/names_test.go@@ -0,0 +1,140 @@+// 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 "testing"++func TestParseMeshHost(t *testing.T) {+ tests := []struct {+ name string+ host string+ want string+ wantErr bool+ }{+ {"inference service", "openrouter.inference.sam.alt", "inference://openrouter", false},+ {"mcp service", "code-reviewer.mcp.sam.alt", "mcp://code-reviewer", false},+ {"trailing root dot", "calculator.mcp.sam.alt.", "mcp://calculator", false},+ {"uppercase is folded", "Calculator.MCP.Sam.Alt", "mcp://calculator", false},+ {"dotted service name", "my-service.local.mcp.sam.alt", "mcp://my-service.local", false},+ {"underscore service name", "my_service.mcp.sam.alt", "mcp://my_service", false},++ {"local node is not a service", "node.sam.alt", "", true},+ {"unknown service type", "thing.storage.sam.alt", "", true},+ {"missing service type", "calculator.sam.alt", "", true},+ {"zone only", "sam.alt", "", true},+ {"outside the zone", "api.github.com", "", true},+ {"zone as a substring", "evil-sam.alt", "", true},+ {"empty service name", ".mcp.sam.alt", "", true},+ {"empty", "", "", true},+ }++ for _, tc := range tests {+ t.Run(tc.name, func(t *testing.T) {+ got, err := ParseMeshHost(tc.host)+ if tc.wantErr {+ if err == nil {+ t.Fatalf("ParseMeshHost(%q) = %q, want error", tc.host, got)+ }+ return+ }+ if err != nil {+ t.Fatalf("ParseMeshHost(%q) returned error: %v", tc.host, err)+ }+ if got != tc.want {+ t.Errorf("ParseMeshHost(%q) = %q, want %q", tc.host, got, tc.want)+ }+ })+ }+}++func TestMeshHostRoundTrip(t *testing.T) {+ tests := []struct {+ svcType ServiceType+ name string+ want string+ wantURI string+ }{+ {ServiceType_SERVICE_TYPE_MCP, "calculator", "calculator.mcp.sam.alt", "mcp://calculator"},+ {ServiceType_SERVICE_TYPE_INFERENCE, "openrouter", "openrouter.inference.sam.alt", "inference://openrouter"},+ }++ for _, tc := range tests {+ t.Run(tc.name, func(t *testing.T) {+ host, err := MeshHost(tc.svcType, tc.name)+ if err != nil {+ t.Fatalf("MeshHost(%v, %q) returned error: %v", tc.svcType, tc.name, err)+ }+ if host != tc.want {+ t.Fatalf("MeshHost(%v, %q) = %q, want %q", tc.svcType, tc.name, host, tc.want)+ }+ uri, err := ParseMeshHost(host)+ if err != nil {+ t.Fatalf("ParseMeshHost(%q) returned error: %v", host, err)+ }+ if uri != tc.wantURI {+ t.Errorf("round trip of %q = %q, want %q", tc.name, uri, tc.wantURI)+ }+ })+ }+}++func TestMeshHostRejects(t *testing.T) {+ tests := []struct {+ name string+ svcType ServiceType+ svcName string+ }{+ {"unspecified type", ServiceType_SERVICE_TYPE_UNSPECIFIED, "calculator"},+ {"empty name", ServiceType_SERVICE_TYPE_MCP, ""},+ {"uppercase name is not addressable", ServiceType_SERVICE_TYPE_MCP, "Calculator"},+ {"name with a path", ServiceType_SERVICE_TYPE_MCP, "calculator/add"},+ }++ for _, tc := range tests {+ t.Run(tc.name, func(t *testing.T) {+ if host, err := MeshHost(tc.svcType, tc.svcName); err == nil {+ t.Fatalf("MeshHost(%v, %q) = %q, want error", tc.svcType, tc.svcName, host)+ }+ })+ }+}++func TestIsMeshHostAndIsLocalNodeHost(t *testing.T) {+ tests := []struct {+ host string+ isMesh bool+ isLocal bool+ }{+ {"node.sam.alt", true, true},+ {"NODE.SAM.ALT.", true, true},+ {"calculator.mcp.sam.alt", true, false},+ {"sam.alt", true, false},+ {"api.github.com", false, false},+ {"evil-sam.alt", false, false},+ {"node.sam.alt.evil.com", false, false},+ {"", false, false},+ }++ for _, tc := range tests {+ t.Run(tc.host, func(t *testing.T) {+ if got := IsMeshHost(tc.host); got != tc.isMesh {+ t.Errorf("IsMeshHost(%q) = %v, want %v", tc.host, got, tc.isMesh)+ }+ if got := IsLocalNodeHost(tc.host); got != tc.isLocal {+ t.Errorf("IsLocalNodeHost(%q) = %v, want %v", tc.host, got, tc.isLocal)+ }+ })+ }+}