node: services are declared in configuration, never registered at runtime

Remove the /sam/service/register and /sam/service/unregister endpoints:
anything a caller can mutate at runtime is an interface it can abuse, and
every legitimate use was a declaration in disguise. Services now only
exist by declaration at startup — the node's --config services block, or
the FFI start configuration on mobile — and the probe gates advertisement,
so readiness is observed rather than asserted.

The former endpoint paths fall through to the egress proxy like any other
/sam/ path, with no special handling; the sandbox boundary still refuses
them before the node is ever reached, which the boundary tests keep
pinning. Validation moves into SamNode.RegisterService, the one funnel the
config and FFI paths share.

Tests, harnesses, the mobile app, the Cloud Run example and the
architecture doc's ingress section all migrate to declaring backends
before their node starts. Runtime-written config files are chmod 644: the
node container runs as a non-root user and a restrictive umask would make
the mounted config unreadable inside it.

Author: aojea

.github/k8s/sam-box-canary-template.yaml

@@ -147,7 +147,7 @@ spec:
             echo "the sandbox's interfaces (expect lo and tun0 only): $(ip -o link show | cut -d: -f2 | tr -d ' ' | paste -sd,)"
             while true; do
               echo "allowlisted destination (expect 200): $(curl -s -o /dev/null -w '%{http_code}' http://example.com/)"
-              echo "the node's own API (expect 403): $(curl -s -o /dev/null -w '%{http_code}' http://mesh.sam.alt/sam/service/register)"
+              echo "the node's own API (expect 403): $(curl -s -o /dev/null -w '%{http_code}' http://mesh.sam.alt/sam/service/discover)"
               curl -s -o /dev/null http://blocked.example/ && echo "unlisted destination was NOT refused" || echo "unlisted destination refused (expected)"
               sleep 30
             done

internal/node/node.go

@@ -1580,6 +1580,15 @@ func (n *SamNode) HandleAuthHandshake(s network.Stream) {
 }
 
 func (n *SamNode) RegisterService(ctx context.Context, req *api.RegisterServiceRequest) error {
+	if req.Service == nil {
+		return fmt.Errorf("service field is required")
+	}
+	if req.Service.Name == "" || req.Service.Type == api.ServiceType_SERVICE_TYPE_UNSPECIFIED {
+		return fmt.Errorf("service name and type are required")
+	}
+	if req.Backend == nil {
+		return fmt.Errorf("service backend is required")
+	}
 	svc, err := NewServiceFromRequest(req)
 	if err != nil {
 		return err

internal/node/sidecar.go

@@ -23,7 +23,6 @@ import (
 	"encoding/base64"
 	"encoding/json"
 	"fmt"
-	"io"
 	"net"
 	"net/http"
 	"net/http/httputil"
@@ -38,7 +37,6 @@ import (
 	"github.com/libp2p/go-libp2p/core/network"
 	"github.com/libp2p/go-libp2p/core/peer"
 	"github.com/prometheus/client_golang/prometheus/promhttp"
-	"google.golang.org/protobuf/encoding/protojson"
 )
 
 // StartSidecarServer serves the node's local API on a TCP address, on a Unix
@@ -57,12 +55,10 @@ func StartSidecarServer(node *SamNode, addr, socketPath, token, certFile, keyFil
 
 	// Protected endpoints. allowAuthorizationFallback=true is safe here: none of
 	// these ever forward the inbound Authorization header to another service.
-	mux.Handle("/sam/service/register", withAuth(token, true, withMeshConnection(node, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		handleRegisterService(node, w, r)
-	}))))
-	mux.Handle("/sam/service/unregister", withAuth(token, true, withMeshConnection(node, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		handleUnregisterService(node, w, r)
-	}))))
+	// Services are declared in the node's configuration and registered at
+	// startup; there is deliberately no runtime registration surface, so no
+	// credential held by an agent can point the mesh at a new backend or
+	// withdraw a sibling service.
 	mux.Handle("/sam/service/discover", withAuth(token, true, withMeshConnection(node, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		handleDiscoverService(node, w, r)
 	}))))
@@ -448,90 +444,10 @@ func constantTimeEqual(got, want string) bool {
 	return subtle.ConstantTimeCompare(gotHash[:], wantHash[:]) == 1
 }
 
-type ServiceRequest struct {
-	ServiceName string `json:"service_name"`
-}
-
 // maxRequestBodyBytes caps request bodies read into memory to guard
 // against memory-exhaustion from oversized payloads.
 const maxRequestBodyBytes = 1 << 20 // 1 MiB
 
-func handleRegisterService(node *SamNode, w http.ResponseWriter, r *http.Request) {
-	if r.Method != http.MethodPost {
-		http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
-		return
-	}
-
-	r.Body = http.MaxBytesReader(w, r.Body, maxRequestBodyBytes)
-	body, err := io.ReadAll(r.Body)
-	if err != nil {
-		http.Error(w, "Failed to read request body", http.StatusInternalServerError)
-		return
-	}
-	_ = r.Body.Close()
-
-	var req api.RegisterServiceRequest
-	if err := protojson.Unmarshal(body, &req); err != nil {
-		http.Error(w, fmt.Sprintf("Invalid request body: %v", err), http.StatusBadRequest)
-		return
-	}
-
-	if req.Service == nil {
-		http.Error(w, "service field is required", http.StatusBadRequest)
-		return
-	}
-
-	if req.Service.Name == "" || req.Service.Type == api.ServiceType_SERVICE_TYPE_UNSPECIFIED {
-		http.Error(w, "name and type are required", http.StatusBadRequest)
-		return
-	}
-
-	if req.Backend == nil {
-		http.Error(w, "backend is required", http.StatusBadRequest)
-		return
-	}
-
-	if err := node.RegisterService(r.Context(), &req); err != nil {
-		logger.Errorf("Failed to register service: %v", err)
-		http.Error(w, fmt.Sprintf("Failed to register service: %v", err), http.StatusInternalServerError)
-		return
-	}
-
-	w.WriteHeader(http.StatusOK)
-	if _, err := w.Write([]byte("Service registered")); err != nil {
-		logger.Errorf("Failed to write response: %v", err)
-	}
-}
-
-func handleUnregisterService(node *SamNode, w http.ResponseWriter, r *http.Request) {
-	if r.Method != http.MethodPost {
-		http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
-		return
-	}
-
-	var req api.ServiceInfo
-	r.Body = http.MaxBytesReader(w, r.Body, maxRequestBodyBytes)
-	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
-		http.Error(w, "Invalid request body", http.StatusBadRequest)
-		return
-	}
-
-	if req.Name == "" {
-		http.Error(w, "name is required", http.StatusBadRequest)
-		return
-	}
-
-	if err := node.UnregisterService(r.Context(), req.Name); err != nil {
-		http.Error(w, fmt.Sprintf("Failed to unregister service: %v", err), http.StatusInternalServerError)
-		return
-	}
-
-	w.WriteHeader(http.StatusOK)
-	if _, err := w.Write([]byte("Service unregistered")); err != nil {
-		logger.Errorf("Failed to write response: %v", err)
-	}
-}
-
 func handleDiscoverService(node *SamNode, w http.ResponseWriter, r *http.Request) {
 	if r.Method != http.MethodGet {
 		http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)

internal/node/sidecar_test.go

@@ -15,7 +15,6 @@
 package node
 
 import (
-	"bytes"
 	"context"
 	"encoding/json"
 	"net"
@@ -34,7 +33,6 @@ import (
 	"github.com/libp2p/go-libp2p/core/host"
 	"github.com/libp2p/go-libp2p/core/peer"
 	"github.com/modelcontextprotocol/go-sdk/mcp"
-	"google.golang.org/protobuf/encoding/protojson"
 )
 
 // socketClient talks HTTP over a Unix socket; the host in the URL is ignored.
@@ -406,15 +404,16 @@ func TestSidecarServerAuthEnforcement(t *testing.T) {
 		{"readyz is public", "GET", "/readyz", http.StatusOK, false},
 		// Liveness says nothing; metrics name peers and count their traffic.
 		{"metrics is protected", "GET", "/metrics", http.StatusUnauthorized, false},
-		{"register is protected", "POST", "/sam/service/register", http.StatusUnauthorized, false},
-		{"unregister is protected", "POST", "/sam/service/unregister", http.StatusUnauthorized, false},
+		// Services are declared in configuration only: the former runtime
+		// mutation endpoints are gone, so these paths are plain egress-proxy
+		// paths (503: not connected) with no special handling.
+		{"register does not exist", "POST", "/sam/service/register", http.StatusServiceUnavailable, true},
+		{"unregister does not exist", "POST", "/sam/service/unregister", http.StatusServiceUnavailable, true},
 		{"discover is protected", "GET", "/sam/service/discover?type=mcp&name=test", http.StatusUnauthorized, false},
 		{"egress proxy is protected", "GET", "/sam/", http.StatusUnauthorized, false},
 		{"mcp root is protected", "GET", "/mcp", http.StatusUnauthorized, false},
 
-		{"register with token (bad req)", "POST", "/sam/service/register", http.StatusServiceUnavailable, true},
 		{"metrics with token", "GET", "/metrics", http.StatusOK, true},
-		{"unregister with token (bad req)", "POST", "/sam/service/unregister", http.StatusServiceUnavailable, true},
 		// /sam/service/discover without mesh connection will return 503 instead of 400 since node is not connected,
 		// but as long as it gets past auth, that's what we want to verify.
 		{"discover with token", "GET", "/sam/service/discover?type=mcp&name=test", http.StatusServiceUnavailable, true},
@@ -514,7 +513,7 @@ func TestSidecarAuthorizationFallbackScope(t *testing.T) {
 	}
 }
 
-func TestHandleRegisterService(t *testing.T) {
+func TestRegisterService(t *testing.T) {
 	h, err := libp2p.New(libp2p.ListenAddrStrings("/ip4/127.0.0.1/tcp/0"))
 	if err != nil {
 		t.Fatal(err)
@@ -555,22 +554,12 @@ func TestHandleRegisterService(t *testing.T) {
 	upstream := httptest.NewServer(newFakeMCPHandler(t, []*mcp.Tool{}))
 	defer upstream.Close()
 
-	reqBody := &api.RegisterServiceRequest{
+	req := &api.RegisterServiceRequest{
 		Service: &api.ServiceInfo{Type: api.ServiceType_SERVICE_TYPE_MCP, Name: "test-service", Description: "test desc"},
 		Backend: &api.RegisterServiceRequest_TargetUrl{TargetUrl: upstream.URL},
 	}
-	body, err := protojson.Marshal(reqBody)
-	if err != nil {
-		t.Fatalf("Failed to marshal request body: %v", err)
-	}
-
-	req := httptest.NewRequest("POST", "/sam/service/register", bytes.NewBuffer(body))
-	rr := httptest.NewRecorder()
-
-	handleRegisterService(node, rr, req)
-
-	if rr.Code != http.StatusOK {
-		t.Errorf("expected status OK, got %d, body: %s", rr.Code, rr.Body.String())
+	if err := node.RegisterService(context.Background(), req); err != nil {
+		t.Fatalf("RegisterService: %v", err)
 	}
 
 	if !node.IsServiceRegistered("test-service") {
@@ -584,25 +573,14 @@ func TestHandleRegisterService(t *testing.T) {
 	}
 }
 
-func TestHandleUnregisterService(t *testing.T) {
+func TestUnregisterService(t *testing.T) {
 	node := &SamNode{BiscuitTimeout: 500 * time.Millisecond,
 		services: NewServiceRegistry(&fakeDHT{}),
 	}
 	node.services.insertService(&testService{info: &api.ServiceInfo{Name: "test-service"}})
 
-	reqBody := &api.ServiceInfo{Name: "test-service"}
-	body, err := json.Marshal(reqBody)
-	if err != nil {
-		t.Fatalf("Failed to marshal request body: %v", err)
-	}
-
-	req := httptest.NewRequest("POST", "/sam/service/unregister", bytes.NewBuffer(body))
-	rr := httptest.NewRecorder()
-
-	handleUnregisterService(node, rr, req)
-
-	if rr.Code != http.StatusOK {
-		t.Errorf("expected status OK, got %d", rr.Code)
+	if err := node.UnregisterService(context.Background(), "test-service"); err != nil {
+		t.Fatalf("UnregisterService: %v", err)
 	}
 
 	if node.IsServiceRegistered("test-service") {
@@ -797,61 +775,47 @@ func TestServiceKeyToCID_Equivalence(t *testing.T) {
 	}
 }
 
-func TestHandleRegisterService_Validation(t *testing.T) {
+func TestRegisterService_Validation(t *testing.T) {
 	node := &SamNode{BiscuitTimeout: 500 * time.Millisecond,
 		services: NewServiceRegistry(&fakeDHT{}),
 	}
 
 	tests := []struct {
-		name           string
-		reqBody        *api.RegisterServiceRequest
-		expectedStatus int
+		name    string
+		reqBody *api.RegisterServiceRequest
 	}{
 		{
 			name: "Missing service",
 			reqBody: &api.RegisterServiceRequest{
 				Backend: &api.RegisterServiceRequest_TargetUrl{TargetUrl: "http://localhost:8080"},
 			},
-			expectedStatus: http.StatusBadRequest,
 		},
 		{
 			name: "Missing name",
 			reqBody: &api.RegisterServiceRequest{
 				Service: &api.ServiceInfo{Type: api.ServiceType_SERVICE_TYPE_MCP},
 				Backend: &api.RegisterServiceRequest_TargetUrl{TargetUrl: "http://localhost:8080"},
 			},
-			expectedStatus: http.StatusBadRequest,
 		},
 		{
 			name: "Unspecified type",
 			reqBody: &api.RegisterServiceRequest{
 				Service: &api.ServiceInfo{Name: "test-service", Type: api.ServiceType_SERVICE_TYPE_UNSPECIFIED},
 				Backend: &api.RegisterServiceRequest_TargetUrl{TargetUrl: "http://localhost:8080"},
 			},
-			expectedStatus: http.StatusBadRequest,
 		},
 		{
 			name: "Missing backend",
 			reqBody: &api.RegisterServiceRequest{
 				Service: &api.ServiceInfo{Name: "test-service", Type: api.ServiceType_SERVICE_TYPE_MCP},
 			},
-			expectedStatus: http.StatusBadRequest,
 		},
 	}
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			body, err := protojson.Marshal(tt.reqBody)
-			if err != nil {
-				t.Fatal(err)
-			}
-			req := httptest.NewRequest("POST", "/sam/service/register", bytes.NewBuffer(body))
-			rr := httptest.NewRecorder()
-
-			handleRegisterService(node, rr, req)
-
-			if rr.Code != tt.expectedStatus {
-				t.Errorf("expected status %d, got %d, body: %s", tt.expectedStatus, rr.Code, rr.Body.String())
+			if err := node.RegisterService(context.Background(), tt.reqBody); err == nil {
+				t.Errorf("expected RegisterService to reject invalid request")
 			}
 		})
 	}