Skip to content

Agent Mesh

api: project mesh service names into DNS-shaped hostnames

Antonio Ojea00bc33e597f0
diff --git a/api/names.go b/api/names.go
new file mode 100644
index 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.go
new file mode 100644
index 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)
+ }
+ })
+ }
+}