Enrolled Nodes
+ +
+
+ Mesh Services
+
+
+
+
+
+
+
+ | Service | +Type | +Description | +Node ID | +Reported At | +
|---|---|---|---|---|
| Loading... | ||||
diff --git a/internal/console/public/style.css b/internal/console/public/style.css
index 782e4264..e3b4105d 100644
--- a/internal/console/public/style.css
+++ b/internal/console/public/style.css
@@ -646,6 +646,13 @@ body {
border-bottom: none;
}
+/* An operator-declared label line under a bare peer ID (see peerCell in
+ app.js) - a class, not an inline style, so CSP style-src can stay strict. */
+.cell-subtext {
+ color: var(--text-secondary);
+ font-size: 0.85em;
+}
+
.text-center {
text-align: center;
}
diff --git a/internal/controlplane/catalog.go b/internal/controlplane/catalog.go
new file mode 100644
index 00000000..7ff798cd
--- /dev/null
+++ b/internal/controlplane/catalog.go
@@ -0,0 +1,215 @@
+// 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 controlplane
+
+import (
+ "crypto/ed25519"
+ "encoding/base64"
+ "fmt"
+ "io"
+ "net/http"
+ "strings"
+ "time"
+
+ "github.com/google/sam/api"
+ "github.com/google/sam/internal/identity"
+ "github.com/google/sam/internal/storage"
+ "github.com/libp2p/go-libp2p/core/peer"
+ "google.golang.org/protobuf/proto"
+)
+
+// maxCatalogServices bounds one report so a single admitted node cannot grow
+// the in-memory cache without limit.
+const maxCatalogServices = 512
+
+// nodeCatalogEntry is what HandleNodeCatalog caches per reporting peer.
+type nodeCatalogEntry struct {
+ Services []*api.ServiceInfo
+ ReportedAt time.Time
+}
+
+// catalogService is the console-facing shape of one reported service: a plain
+// struct so the JSON the console reads does not depend on protoc-gen-go's
+// struct layout or tags.
+type catalogService struct {
+ Name string `json:"name"`
+ Type string `json:"type"`
+ Description string `json:"description"`
+}
+
+// catalogView is HandleAdminStatus's node_catalog value for one peer.
+type catalogView struct {
+ Services []catalogService `json:"services"`
+ ReportedAt time.Time `json:"reported_at"`
+}
+
+// catalogSnapshot returns a stable copy of the current node service catalog
+// cache, safe to range over without holding catalogMu.
+func (s *Server) catalogSnapshot() map[string]nodeCatalogEntry {
+ s.catalogMu.RLock()
+ defer s.catalogMu.RUnlock()
+ snap := make(map[string]nodeCatalogEntry, len(s.catalog))
+ for k, v := range s.catalog {
+ snap[k] = v
+ }
+ return snap
+}
+
+// catalogViewFor renders the cache for the console, restricted to nodes that
+// are still admitted so a banned or expired node's last report disappears
+// with its enrollment instead of lingering until the next restart.
+func (s *Server) catalogViewFor(nodes []storage.EnrolledNode, now time.Time) map[string]catalogView {
+ snap := s.catalogSnapshot()
+ view := make(map[string]catalogView, len(snap))
+ for i := range nodes {
+ node := &nodes[i]
+ // The cache is keyed by the canonical base58 form from the verified
+ // biscuit; the stored record may carry another valid encoding of the
+ // same peer (e.g. CIDv1), so decode before looking up.
+ pID, err := peer.Decode(node.PeerID)
+ if err != nil {
+ logger.Warnw("Skipping enrolled node with undecodable peer ID in catalog view", "peer_id", node.PeerID, "error", err)
+ continue
+ }
+ entry, ok := snap[pID.String()]
+ if !ok || node.CheckAdmission(now) != nil {
+ continue
+ }
+ services := make([]catalogService, 0, len(entry.Services))
+ for _, svc := range entry.Services {
+ if svc == nil {
+ continue
+ }
+ typeName, err := api.ServiceTypeToString(svc.GetType())
+ if err != nil {
+ typeName = "unknown"
+ }
+ services = append(services, catalogService{
+ Name: svc.GetName(),
+ Type: typeName,
+ Description: svc.GetDescription(),
+ })
+ }
+ view[node.PeerID] = catalogView{Services: services, ReportedAt: entry.ReportedAt}
+ }
+ return view
+}
+
+// dropCatalogEntry forgets a peer's report; called when its enrollment ends.
+// Accepts any valid encoding of the peer ID.
+func (s *Server) dropCatalogEntry(peerID string) {
+ pID, err := peer.Decode(peerID)
+ if err != nil {
+ // Cache keys always come from a verified biscuit, so an undecodable
+ // ID cannot have an entry - nothing to evict, but say so.
+ logger.Warnw("Not evicting catalog entry for undecodable peer ID", "peer_id", peerID, "error", err)
+ return
+ }
+ s.catalogMu.Lock()
+ delete(s.catalog, pID.String())
+ s.catalogMu.Unlock()
+}
+
+// HandleNodeCatalog HTTP POST /nodes/catalog - a node self-reports the
+// services it currently has registered locally (the same data
+// list_local_services already answers on the node itself), so the control
+// plane can show mesh-wide service topology without needing to be a DHT
+// participant or open a P2P connection to every enrolled node itself.
+//
+// The body is an api.NodeCatalogReport. The reporting peer is the one bound
+// in the presented Biscuit, so a node can only ever describe itself.
+//
+// This is a live-status cache, not authoritative state: a node that goes
+// offline without ever reporting an empty catalog just leaves its last
+// report in place until ReportedAt visibly goes stale or its enrollment
+// ends. It is admin-facing display data only and never feeds authorization,
+// which is also why a bare bearer Biscuit (no signed challenge, unlike
+// /refresh) is accepted here: a replayed token can only repaint a table.
+func (s *Server) HandleNodeCatalog(w http.ResponseWriter, r *http.Request) {
+ if r.Method != http.MethodPost {
+ http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
+ return
+ }
+
+ authHeader := r.Header.Get("Authorization")
+ if !strings.HasPrefix(authHeader, "Bearer ") {
+ http.Error(w, "Missing node Biscuit token in Authorization header", http.StatusUnauthorized)
+ return
+ }
+ biscuitBytes, err := base64.StdEncoding.DecodeString(strings.TrimPrefix(authHeader, "Bearer "))
+ if err != nil {
+ http.Error(w, "Malformed base64 token", http.StatusBadRequest)
+ return
+ }
+
+ ctx := r.Context()
+ validKeys, err := s.store.GetAllValidKeys(ctx)
+ if err != nil {
+ logger.Errorf("Failed to retrieve valid signing keys: %v", err)
+ http.Error(w, "Internal server error", http.StatusInternalServerError)
+ return
+ }
+ var trustedKeys []ed25519.PublicKey
+ for _, k := range validKeys {
+ trustedKeys = append(trustedKeys, k.Public)
+ }
+
+ peerID, err := identity.VerifyAndExtractPeerID(trustedKeys, biscuitBytes, s.config.BiscuitTimeout)
+ if err != nil {
+ logger.Warnw("Invalid biscuit presented to /nodes/catalog", "error", err)
+ http.Error(w, "Invalid biscuit: "+err.Error(), http.StatusUnauthorized)
+ return
+ }
+
+ nodeRecord, err := s.store.GetNode(ctx, peerID.String())
+ if err == storage.ErrNotFound || (err == nil && nodeRecord == nil) {
+ http.Error(w, "Node not enrolled", http.StatusUnauthorized)
+ return
+ } else if err != nil {
+ logger.Errorf("Failed to retrieve node record: %v", err)
+ http.Error(w, "Internal server error", http.StatusInternalServerError)
+ return
+ }
+ if err := nodeRecord.CheckAdmission(time.Now()); err != nil {
+ http.Error(w, "Node not admitted: "+err.Error(), http.StatusUnauthorized)
+ return
+ }
+
+ r.Body = http.MaxBytesReader(w, r.Body, maxRequestBodyBytes)
+ body, err := io.ReadAll(r.Body)
+ if err != nil {
+ http.Error(w, "Failed to read body", http.StatusBadRequest)
+ return
+ }
+
+ var req api.NodeCatalogReport
+ if err := proto.Unmarshal(body, &req); err != nil {
+ http.Error(w, "Invalid request format", http.StatusBadRequest)
+ return
+ }
+ if len(req.Services) > maxCatalogServices {
+ http.Error(w, fmt.Sprintf("Too many services in report (max %d)", maxCatalogServices), http.StatusBadRequest)
+ return
+ }
+
+ s.catalogMu.Lock()
+ s.catalog[peerID.String()] = nodeCatalogEntry{
+ Services: req.Services,
+ ReportedAt: time.Now(),
+ }
+ s.catalogMu.Unlock()
+
+ w.WriteHeader(http.StatusNoContent)
+}
diff --git a/internal/controlplane/catalog_test.go b/internal/controlplane/catalog_test.go
new file mode 100644
index 00000000..aa28b252
--- /dev/null
+++ b/internal/controlplane/catalog_test.go
@@ -0,0 +1,354 @@
+// 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 controlplane
+
+import (
+ "bytes"
+ "context"
+ "crypto/ed25519"
+ "encoding/base64"
+ "encoding/json"
+ "net/http"
+ "testing"
+ "time"
+
+ "github.com/google/sam/api"
+ "github.com/google/sam/internal/identity"
+ "github.com/libp2p/go-libp2p/core/crypto"
+ "github.com/libp2p/go-libp2p/core/peer"
+ "google.golang.org/protobuf/proto"
+)
+
+// postCatalog POSTs a raw body to /nodes/catalog under the given
+// Authorization header value and returns the response status.
+func postCatalog(t *testing.T, cpURL, authHeader string, body []byte) int {
+ t.Helper()
+
+ req, err := http.NewRequest(http.MethodPost, cpURL+"/nodes/catalog", bytes.NewReader(body))
+ if err != nil {
+ t.Fatalf("NewRequest: %v", err)
+ }
+ if authHeader != "" {
+ req.Header.Set("Authorization", authHeader)
+ }
+ req.Header.Set("Content-Type", "application/x-protobuf")
+
+ resp, err := http.DefaultClient.Do(req)
+ if err != nil {
+ t.Fatalf("Do: %v", err)
+ }
+ defer func() { _ = resp.Body.Close() }()
+ return resp.StatusCode
+}
+
+func bearer(biscuit []byte) string {
+ return "Bearer " + base64.StdEncoding.EncodeToString(biscuit)
+}
+
+func catalogBody(t *testing.T, services ...*api.ServiceInfo) []byte {
+ t.Helper()
+ body, err := proto.Marshal(&api.NodeCatalogReport{Services: services})
+ if err != nil {
+ t.Fatalf("Marshal: %v", err)
+ }
+ return body
+}
+
+// adminNodeCatalog fetches /admin/status and returns its node_catalog value.
+func adminNodeCatalog(t *testing.T, cpURL, adminToken string) map[string]catalogView {
+ t.Helper()
+
+ req, err := http.NewRequest(http.MethodGet, cpURL+"/admin/status", nil)
+ if err != nil {
+ t.Fatalf("NewRequest: %v", err)
+ }
+ req.Header.Set("Authorization", "Bearer "+adminToken)
+ resp, err := http.DefaultClient.Do(req)
+ if err != nil {
+ t.Fatalf("GET /admin/status: %v", err)
+ }
+ defer func() { _ = resp.Body.Close() }()
+ if resp.StatusCode != http.StatusOK {
+ t.Fatalf("GET /admin/status: status %d", resp.StatusCode)
+ }
+ var status struct {
+ NodeCatalog map[string]catalogView `json:"node_catalog"`
+ }
+ if err := json.NewDecoder(resp.Body).Decode(&status); err != nil {
+ t.Fatalf("decode /admin/status: %v", err)
+ }
+ return status.NodeCatalog
+}
+
+func TestHandleNodeCatalog(t *testing.T) {
+ t.Parallel()
+
+ srv, store, cpURL := setupTestServer(t, "")
+ defer func() {
+ _ = srv.Close()
+ _ = store.Close()
+ }()
+ srv.config.AdminToken = "super-secret-admin-token"
+
+ ctx := context.Background()
+ priv, biscuitBytes := enrollRefreshTestNode(t, ctx, store)
+ nodePeer, err := peer.IDFromPrivateKey(priv)
+ if err != nil {
+ t.Fatalf("IDFromPrivateKey: %v", err)
+ }
+
+ body := catalogBody(t,
+ &api.ServiceInfo{Type: api.ServiceType_SERVICE_TYPE_MCP, Name: "stvv-compliance-docs", Description: "doc lookup"},
+ &api.ServiceInfo{Type: api.ServiceType_SERVICE_TYPE_INFERENCE, Name: "llama", Description: "local model"},
+ )
+ if got := postCatalog(t, cpURL, bearer(biscuitBytes), body); got != http.StatusNoContent {
+ t.Fatalf("HandleNodeCatalog: got status %d, want %d", got, http.StatusNoContent)
+ }
+
+ snap := srv.catalogSnapshot()
+ entry, ok := snap[nodePeer.String()]
+ if !ok || len(snap) != 1 {
+ t.Fatalf("expected exactly the reporting peer in the catalog, got %v", snap)
+ }
+ if len(entry.Services) != 2 || entry.ReportedAt.IsZero() {
+ t.Fatalf("unexpected cached entry: %+v", entry)
+ }
+
+ // A second report replaces the first rather than accumulating.
+ body = catalogBody(t, &api.ServiceInfo{Type: api.ServiceType_SERVICE_TYPE_A2A, Name: "planner"})
+ if got := postCatalog(t, cpURL, bearer(biscuitBytes), body); got != http.StatusNoContent {
+ t.Fatalf("second report: got status %d, want %d", got, http.StatusNoContent)
+ }
+ entry = srv.catalogSnapshot()[nodePeer.String()]
+ if len(entry.Services) != 1 || entry.Services[0].Name != "planner" {
+ t.Fatalf("second report must replace the first, got %+v", entry.Services)
+ }
+
+ // The console sees the plain view with the type rendered as a name.
+ view := adminNodeCatalog(t, cpURL, srv.config.AdminToken)
+ got, ok := view[nodePeer.String()]
+ if !ok || len(view) != 1 {
+ t.Fatalf("expected the reporting peer in node_catalog, got %v", view)
+ }
+ want := []catalogService{{Name: "planner", Type: "a2a", Description: ""}}
+ if len(got.Services) != 1 || got.Services[0] != want[0] || got.ReportedAt.IsZero() {
+ t.Fatalf("node_catalog view = %+v, want services %+v", got, want)
+ }
+
+ // An empty report is valid and clears the node's services.
+ if got := postCatalog(t, cpURL, bearer(biscuitBytes), catalogBody(t)); got != http.StatusNoContent {
+ t.Fatalf("empty report: got status %d, want %d", got, http.StatusNoContent)
+ }
+ if view := adminNodeCatalog(t, cpURL, srv.config.AdminToken); len(view[nodePeer.String()].Services) != 0 {
+ t.Fatalf("empty report must clear services, got %+v", view)
+ }
+}
+
+func TestHandleNodeCatalog_Rejections(t *testing.T) {
+ t.Parallel()
+
+ srv, store, cpURL := setupTestServer(t, "")
+ defer func() {
+ _ = srv.Close()
+ _ = store.Close()
+ }()
+
+ ctx := context.Background()
+ _, biscuitBytes := enrollRefreshTestNode(t, ctx, store)
+ cpPriv, _, err := store.GetCurrentKey(ctx)
+ if err != nil {
+ t.Fatalf("GetCurrentKey: %v", err)
+ }
+
+ // A biscuit minted by a key the control plane never trusted.
+ _, rogueKey, err := ed25519.GenerateKey(nil)
+ if err != nil {
+ t.Fatalf("GenerateKey: %v", err)
+ }
+ strangerPriv, _, err := crypto.GenerateKeyPair(crypto.Ed25519, -1)
+ if err != nil {
+ t.Fatalf("GenerateKeyPair: %v", err)
+ }
+ strangerPeer, err := peer.IDFromPrivateKey(strangerPriv)
+ if err != nil {
+ t.Fatalf("IDFromPrivateKey: %v", err)
+ }
+ forged, err := identity.MintBootstrapBiscuitToken(rogueKey, strangerPeer, api.RoleNode, time.Now().Add(api.BiscuitTokenTTL), nil, nil)
+ if err != nil {
+ t.Fatalf("MintBootstrapBiscuitToken(rogue): %v", err)
+ }
+ // A valid biscuit for a peer that was never enrolled.
+ unenrolled, err := identity.MintBootstrapBiscuitToken(cpPriv, strangerPeer, api.RoleNode, time.Now().Add(api.BiscuitTokenTTL), nil, nil)
+ if err != nil {
+ t.Fatalf("MintBootstrapBiscuitToken(unenrolled): %v", err)
+ }
+
+ tooMany := make([]*api.ServiceInfo, maxCatalogServices+1)
+ for i := range tooMany {
+ tooMany[i] = &api.ServiceInfo{Type: api.ServiceType_SERVICE_TYPE_MCP, Name: "svc"}
+ }
+
+ ok := catalogBody(t)
+ tests := []struct {
+ name string
+ auth string
+ body []byte
+ want int
+ }{
+ {name: "missing authorization", auth: "", body: ok, want: http.StatusUnauthorized},
+ {name: "not a bearer token", auth: "Basic abc", body: ok, want: http.StatusUnauthorized},
+ {name: "malformed base64", auth: "Bearer %%%not-base64", body: ok, want: http.StatusBadRequest},
+ {name: "not a biscuit", auth: bearer([]byte("garbage")), body: ok, want: http.StatusUnauthorized},
+ {name: "forged signature", auth: bearer(forged), body: ok, want: http.StatusUnauthorized},
+ {name: "unenrolled peer", auth: bearer(unenrolled), body: ok, want: http.StatusUnauthorized},
+ {name: "invalid body", auth: bearer(biscuitBytes), body: []byte(`{"services":[]}`), want: http.StatusBadRequest},
+ {name: "too many services", auth: bearer(biscuitBytes), body: catalogBody(t, tooMany...), want: http.StatusBadRequest},
+ }
+ for _, tc := range tests {
+ t.Run(tc.name, func(t *testing.T) {
+ if got := postCatalog(t, cpURL, tc.auth, tc.body); got != tc.want {
+ t.Fatalf("got status %d, want %d", got, tc.want)
+ }
+ })
+ }
+ if len(srv.catalogSnapshot()) != 0 {
+ t.Fatalf("rejected reports must not be cached, got %v", srv.catalogSnapshot())
+ }
+
+ resp, err := http.Get(cpURL + "/nodes/catalog")
+ if err != nil {
+ t.Fatalf("Get: %v", err)
+ }
+ _ = resp.Body.Close()
+ if resp.StatusCode != http.StatusMethodNotAllowed {
+ t.Fatalf("GET /nodes/catalog: got status %d, want %d", resp.StatusCode, http.StatusMethodNotAllowed)
+ }
+}
+
+// A node's catalog is only ever as trustworthy as its enrollment: once the
+// record is banned or its session lapses, new reports are refused and the
+// cached one drops out of the console view.
+func TestHandleNodeCatalog_Admission(t *testing.T) {
+ t.Parallel()
+
+ srv, store, cpURL := setupTestServer(t, "")
+ defer func() {
+ _ = srv.Close()
+ _ = store.Close()
+ }()
+ srv.config.AdminToken = "super-secret-admin-token"
+
+ ctx := context.Background()
+ priv, biscuitBytes := enrollRefreshTestNode(t, ctx, store)
+ nodePeer, err := peer.IDFromPrivateKey(priv)
+ if err != nil {
+ t.Fatalf("IDFromPrivateKey: %v", err)
+ }
+ body := catalogBody(t, &api.ServiceInfo{Type: api.ServiceType_SERVICE_TYPE_MCP, Name: "calc"})
+ if got := postCatalog(t, cpURL, bearer(biscuitBytes), body); got != http.StatusNoContent {
+ t.Fatalf("admitted node: got status %d, want %d", got, http.StatusNoContent)
+ }
+ if _, ok := adminNodeCatalog(t, cpURL, srv.config.AdminToken)[nodePeer.String()]; !ok {
+ t.Fatal("admitted node's report missing from node_catalog")
+ }
+
+ // Session lapsed: the cache still holds the report but the view hides it.
+ record, err := store.GetNode(ctx, nodePeer.String())
+ if err != nil {
+ t.Fatalf("GetNode: %v", err)
+ }
+ record.ExpiresAt = time.Now().Add(-time.Hour)
+ if err := store.EnrollNode(ctx, record); err != nil {
+ t.Fatalf("EnrollNode: %v", err)
+ }
+ if got := postCatalog(t, cpURL, bearer(biscuitBytes), body); got != http.StatusUnauthorized {
+ t.Fatalf("expired session: got status %d, want %d", got, http.StatusUnauthorized)
+ }
+ if view := adminNodeCatalog(t, cpURL, srv.config.AdminToken); len(view) != 0 {
+ t.Fatalf("expired node must not appear in node_catalog, got %v", view)
+ }
+
+ // Banned through the server path: the entry is evicted outright.
+ record.ExpiresAt = time.Now().Add(time.Hour)
+ if err := store.EnrollNode(ctx, record); err != nil {
+ t.Fatalf("EnrollNode: %v", err)
+ }
+ if err := srv.banNode(ctx, record); err != nil {
+ t.Fatalf("banNode: %v", err)
+ }
+ if got := postCatalog(t, cpURL, bearer(biscuitBytes), body); got != http.StatusUnauthorized {
+ t.Fatalf("banned node: got status %d, want %d", got, http.StatusUnauthorized)
+ }
+ if snap := srv.catalogSnapshot(); len(snap) != 0 {
+ t.Fatalf("banning must evict the cached report, got %v", snap)
+ }
+}
+
+// The cache is keyed by the canonical base58 form from the verified biscuit,
+// but the enrollment record's PeerID comes off the wire and may be any valid
+// encoding of the same peer (e.g. CIDv1 base32). The view lookup and the
+// ban eviction must still hit the entry.
+func TestCatalogPeerIDCanonicalization(t *testing.T) {
+ t.Parallel()
+
+ srv, store, cpURL := setupTestServer(t, "")
+ defer func() {
+ _ = srv.Close()
+ _ = store.Close()
+ }()
+ srv.config.AdminToken = "super-secret-admin-token"
+
+ ctx := context.Background()
+ priv, biscuitBytes := enrollRefreshTestNode(t, ctx, store)
+ nodePeer, err := peer.IDFromPrivateKey(priv)
+ if err != nil {
+ t.Fatalf("IDFromPrivateKey: %v", err)
+ }
+
+ // Re-enroll the same peer under its CIDv1 base32 encoding, as a raw wire
+ // string would arrive before the in-flight canonicalization PR lands.
+ record, err := store.GetNode(ctx, nodePeer.String())
+ if err != nil {
+ t.Fatalf("GetNode: %v", err)
+ }
+ cidForm := peer.ToCid(nodePeer).String()
+ if cidForm == nodePeer.String() {
+ t.Fatal("test needs a non-canonical encoding, got the canonical one")
+ }
+ record.PeerID = cidForm
+ if err := store.EnrollNode(ctx, record); err != nil {
+ t.Fatalf("EnrollNode: %v", err)
+ }
+
+ body := catalogBody(t, &api.ServiceInfo{Type: api.ServiceType_SERVICE_TYPE_MCP, Name: "calc"})
+ if got := postCatalog(t, cpURL, bearer(biscuitBytes), body); got != http.StatusNoContent {
+ t.Fatalf("report: got status %d, want %d", got, http.StatusNoContent)
+ }
+
+ // The view must join the CIDv1 record with the canonically-keyed entry,
+ // displayed under the record's own spelling.
+ view := adminNodeCatalog(t, cpURL, srv.config.AdminToken)
+ if _, ok := view[cidForm]; !ok || len(view[cidForm].Services) != 1 {
+ t.Fatalf("CIDv1-enrolled node's report missing from node_catalog, got %v", view)
+ }
+
+ // Ban via the stored record: eviction must hit the canonical cache key.
+ if err := srv.banNode(ctx, record); err != nil {
+ t.Fatalf("banNode: %v", err)
+ }
+ if snap := srv.catalogSnapshot(); len(snap) != 0 {
+ t.Fatalf("banning a CIDv1-enrolled node must evict its cached report, got %v", snap)
+ }
+}
diff --git a/internal/controlplane/server.go b/internal/controlplane/server.go
index 5f398ba9..565a1c47 100644
--- a/internal/controlplane/server.go
+++ b/internal/controlplane/server.go
@@ -77,6 +77,13 @@ type Server struct {
providersMu sync.RWMutex
providers map[string]*oidc.Provider
+ // catalogMu/catalog cache each node's self-reported local service list
+ // (see HandleNodeCatalog), keyed by peer ID. In-memory only: this is a
+ // live-status view, not authoritative state, so it's fine to lose on
+ // restart - every node re-reports on its own next periodic push.
+ catalogMu sync.RWMutex
+ catalog map[string]nodeCatalogEntry
+
ctx context.Context
cancel context.CancelFunc
wg sync.WaitGroup
@@ -98,6 +105,7 @@ func NewServer(config Options, store storage.Store) (*Server, error) {
mesh: NewNopMeshAdapter(),
limiter: rate.NewLimiter(rate.Limit(EnrollRateLimit), EnrollBurst),
providers: make(map[string]*oidc.Provider),
+ catalog: make(map[string]nodeCatalogEntry),
ctx: ctx,
cancel: cancel,
}, nil
@@ -204,6 +212,7 @@ func (s *Server) RegisterRoutes(mux *http.ServeMux) {
mux.HandleFunc("/enroll", s.HandleEnroll)
mux.HandleFunc("/enroll/status", s.HandleEnrollStatus)
mux.HandleFunc("/refresh", s.HandleRefresh)
+ mux.HandleFunc("/nodes/catalog", s.HandleNodeCatalog)
mux.HandleFunc("/admin/bootstrap-tokens", s.HandleAdminBootstrapTokens)
mux.HandleFunc("/admin/enrollments", s.HandleAdminEnrollments)
mux.HandleFunc("/admin/enrollments/", s.HandleAdminEnrollmentAction)
@@ -2177,6 +2186,7 @@ func (s *Server) banNode(ctx context.Context, node *storage.EnrolledNode) error
if err := s.store.SetNodeBanned(ctx, node.PeerID, true); err != nil {
return err
}
+ s.dropCatalogEntry(node.PeerID)
if node.ClaimsJSON == "" {
return nil
}
diff --git a/internal/controlplane/ui.go b/internal/controlplane/ui.go
index cb688fcb..064f5a04 100644
--- a/internal/controlplane/ui.go
+++ b/internal/controlplane/ui.go
@@ -17,6 +17,7 @@ package controlplane
import (
"encoding/json"
"net/http"
+ "time"
)
// HandleAdminStatus returns a consolidated JSON state of the control plane.
@@ -86,6 +87,7 @@ func (s *Server) HandleAdminStatus(w http.ResponseWriter, r *http.Request) {
"enrollment_requests": reqs,
"bootstrap_tokens": tokens,
"policy_json": policyJSON,
+ "node_catalog": s.catalogViewFor(nodes, time.Now()),
}
w.Header().Set("Content-Type", "application/json")
diff --git a/internal/node/controlplane.go b/internal/node/controlplane.go
index de40ed4a..b05392ee 100644
--- a/internal/node/controlplane.go
+++ b/internal/node/controlplane.go
@@ -251,3 +251,40 @@ func FetchMeshPolicy(ctx context.Context, controlPlaneURL string, biscuitToken [
return &policyResp, nil
}
+
+// ReportNodeCatalog self-reports this node's locally registered services to
+// the control plane's /nodes/catalog endpoint, so an admin can see mesh-wide
+// service topology (see catalog.go's HandleNodeCatalog for why this exists
+// instead of the control plane discovering it via DHT/P2P itself).
+func ReportNodeCatalog(ctx context.Context, controlPlaneURL string, biscuitToken []byte, services []*api.ServiceInfo) error {
+ if !strings.HasPrefix(controlPlaneURL, "http://") && !strings.HasPrefix(controlPlaneURL, "https://") {
+ controlPlaneURL = "https://" + controlPlaneURL
+ }
+ controlPlaneURL = strings.TrimSuffix(controlPlaneURL, "/")
+
+ payload, err := proto.Marshal(&api.NodeCatalogReport{Services: services})
+ if err != nil {
+ return fmt.Errorf("failed to encode catalog report: %w", err)
+ }
+
+ urlStr := controlPlaneURL + "/nodes/catalog"
+ req, err := http.NewRequestWithContext(ctx, "POST", urlStr, bytes.NewReader(payload))
+ if err != nil {
+ return fmt.Errorf("failed to create HTTP request: %w", err)
+ }
+ req.Header.Set("Content-Type", "application/x-protobuf")
+ req.Header.Set("Authorization", "Bearer "+base64.StdEncoding.EncodeToString(biscuitToken))
+
+ client := &http.Client{Timeout: 10 * time.Second}
+ resp, err := client.Do(req)
+ if err != nil {
+ return fmt.Errorf("HTTP request failed: %w", err)
+ }
+ defer resp.Body.Close() //nolint:errcheck
+
+ if resp.StatusCode != http.StatusNoContent {
+ body, _ := io.ReadAll(io.LimitReader(resp.Body, 4096))
+ return fmt.Errorf("control plane returned status %s: %s", resp.Status, string(body))
+ }
+ return nil
+}
diff --git a/internal/node/controlplane_test.go b/internal/node/controlplane_test.go
index e47508e3..38469539 100644
--- a/internal/node/controlplane_test.go
+++ b/internal/node/controlplane_test.go
@@ -17,6 +17,8 @@ package node
import (
"context"
"crypto/ed25519"
+ "encoding/base64"
+ "io"
"net/http"
"net/http/httptest"
"reflect"
@@ -220,3 +222,161 @@ func TestSyncMeshConfig(t *testing.T) {
t.Errorf("Expected saved addrs %v, got %v", expectedInfo.RouterAddresses, savedAddrsStr)
}
}
+
+func TestReportNodeCatalog(t *testing.T) {
+ services := []*api.ServiceInfo{
+ {Type: api.ServiceType_SERVICE_TYPE_MCP, Name: "stvv-compliance-docs", Description: "doc lookup"},
+ }
+
+ var gotAuth, gotContentType string
+ var gotReq api.NodeCatalogReport
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ if r.Method != http.MethodPost {
+ t.Errorf("Expected POST, got %s", r.Method)
+ }
+ if r.URL.Path != "/nodes/catalog" {
+ t.Errorf("Expected path /nodes/catalog, got %s", r.URL.Path)
+ }
+ gotAuth = r.Header.Get("Authorization")
+ gotContentType = r.Header.Get("Content-Type")
+ body, err := io.ReadAll(r.Body)
+ if err != nil {
+ t.Errorf("failed to read request body: %v", err)
+ }
+ if err := proto.Unmarshal(body, &gotReq); err != nil {
+ t.Errorf("failed to decode request body: %v", err)
+ }
+ w.WriteHeader(http.StatusNoContent)
+ }))
+ defer server.Close()
+
+ biscuitToken := []byte("fake-biscuit-bytes")
+ if err := ReportNodeCatalog(context.Background(), server.URL, biscuitToken, services); err != nil {
+ t.Fatalf("ReportNodeCatalog failed: %v", err)
+ }
+
+ wantAuth := "Bearer " + base64.StdEncoding.EncodeToString(biscuitToken)
+ if gotAuth != wantAuth {
+ t.Errorf("Expected Authorization header %q, got %q", wantAuth, gotAuth)
+ }
+ if gotContentType != "application/x-protobuf" {
+ t.Errorf("Expected Content-Type application/x-protobuf, got %q", gotContentType)
+ }
+ if len(gotReq.Services) != 1 || gotReq.Services[0].Name != "stvv-compliance-docs" || gotReq.Services[0].Type != api.ServiceType_SERVICE_TYPE_MCP {
+ t.Errorf("Expected relayed services %v, got %v", services, gotReq.Services)
+ }
+}
+
+func TestReportNodeCatalog_HTTPError(t *testing.T) {
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ http.Error(w, "node not enrolled or not admitted", http.StatusUnauthorized)
+ }))
+ defer server.Close()
+
+ err := ReportNodeCatalog(context.Background(), server.URL, []byte("fake-biscuit-bytes"), nil)
+ if err == nil {
+ t.Fatal("Expected error, got nil")
+ }
+ if !strings.Contains(err.Error(), "control plane returned status 401") {
+ t.Errorf("Expected error to mention status 401, got %v", err)
+ }
+}
+
+// newCatalogTestNode is a SamNode with just enough state for the catalog
+// loop: a store holding the control-plane URL, a cached identity, and a
+// registry with one service.
+func newCatalogTestNode(t *testing.T, controlPlaneURL string) *SamNode {
+ t.Helper()
+ store, err := NewStore(t.TempDir())
+ if err != nil {
+ t.Fatalf("NewStore: %v", err)
+ }
+ t.Cleanup(func() { _ = store.Close() })
+ if controlPlaneURL != "" {
+ if err := store.SaveControlPlaneURL(controlPlaneURL); err != nil {
+ t.Fatalf("SaveControlPlaneURL: %v", err)
+ }
+ }
+ node := &SamNode{Store: store, services: newServiceRegistryForTest(&fakeDHT{})}
+ node.services.insertService(newFakeSvc("calc", api.ServiceType_SERVICE_TYPE_MCP))
+ return node
+}
+
+func TestReportNodeCatalog_Preconditions(t *testing.T) {
+ noURL := newCatalogTestNode(t, "")
+ noURL.SetIdentityCache([]byte("biscuit"))
+ if err := noURL.reportNodeCatalog(context.Background()); err == nil || !strings.Contains(err.Error(), "control plane URL") {
+ t.Errorf("without a control-plane URL: got %v, want a URL error", err)
+ }
+
+ noIdentity := newCatalogTestNode(t, "http://127.0.0.1:1")
+ if err := noIdentity.reportNodeCatalog(context.Background()); err == nil || !strings.Contains(err.Error(), "identity") {
+ t.Errorf("without an identity: got %v, want an identity error", err)
+ }
+}
+
+// The loop must report once after the initial delay and then keep reporting
+// every interval, carrying the live service list each time.
+func TestStartCatalogReportLoop(t *testing.T) {
+ reports := make(chan *api.NodeCatalogReport, 16)
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ if r.URL.Path != "/nodes/catalog" || r.Method != http.MethodPost {
+ t.Errorf("unexpected request %s %s", r.Method, r.URL.Path)
+ }
+ body, _ := io.ReadAll(r.Body)
+ var report api.NodeCatalogReport
+ if err := proto.Unmarshal(body, &report); err != nil {
+ t.Errorf("decode report: %v", err)
+ }
+ reports <- &report
+ w.WriteHeader(http.StatusNoContent)
+ }))
+ defer server.Close()
+
+ node := newCatalogTestNode(t, server.URL)
+ node.SetIdentityCache([]byte("biscuit"))
+
+ ctx, cancel := context.WithCancel(context.Background())
+ defer cancel()
+ node.startCatalogReportLoop(ctx, 10*time.Millisecond, 20*time.Millisecond)
+
+ for i := 0; i < 3; i++ {
+ select {
+ case report := <-reports:
+ if len(report.Services) != 1 || report.Services[0].Name != "calc" {
+ t.Fatalf("report %d: got services %v, want [calc]", i, report.Services)
+ }
+ case <-time.After(5 * time.Second):
+ t.Fatalf("timed out waiting for report %d", i)
+ }
+ }
+
+ // Cancelling stops the loop: no report after the in-flight one settles.
+ cancel()
+ time.Sleep(100 * time.Millisecond)
+ for len(reports) > 0 {
+ <-reports
+ }
+ select {
+ case <-reports:
+ t.Fatal("loop kept reporting after context cancellation")
+ case <-time.After(150 * time.Millisecond):
+ }
+}
+
+func TestOptionsDefault_CatalogReport(t *testing.T) {
+ var o Options
+ o.Default()
+ if o.CatalogReportInterval != time.Minute {
+ t.Errorf("CatalogReportInterval = %v, want 1m", o.CatalogReportInterval)
+ }
+ if o.CatalogReportInitialDelay != 5*time.Second {
+ t.Errorf("CatalogReportInitialDelay = %v, want 5s", o.CatalogReportInitialDelay)
+ }
+
+ custom := Options{CatalogReportInterval: 3 * time.Second, CatalogReportInitialDelay: time.Second}
+ custom.Default()
+ if custom.CatalogReportInterval != 3*time.Second || custom.CatalogReportInitialDelay != time.Second {
+ t.Errorf("Default overwrote explicit values: %+v", custom)
+ }
+}
diff --git a/internal/node/node.go b/internal/node/node.go
index cf934824..b784588d 100644
--- a/internal/node/node.go
+++ b/internal/node/node.go
@@ -631,6 +631,10 @@ func (n *SamNode) Start(ctx context.Context) error {
// Periodically sync mesh policy
n.startPolicySyncLoop(ctx, n.config.PolicySyncInterval)
+ // Periodically self-report local services to the control plane, so an
+ // admin can see mesh-wide service topology.
+ n.startCatalogReportLoop(ctx, n.config.CatalogReportInitialDelay, n.config.CatalogReportInterval)
+
return nil
}
@@ -2208,6 +2212,72 @@ func (n *SamNode) syncMeshPolicy(ctx context.Context) error {
return nil
}
+// reportNodeCatalog self-reports this node's local service list to the
+// control plane (see internal/controlplane/catalog.go's HandleNodeCatalog),
+// so an admin console can show mesh-wide service topology.
+func (n *SamNode) reportNodeCatalog(ctx context.Context) error {
+ controlPlaneURL, err := n.Store.LoadControlPlaneURL()
+ if err != nil || controlPlaneURL == "" {
+ return fmt.Errorf("control plane URL not found in store")
+ }
+
+ token := n.GetIdentity()
+ if len(token) == 0 {
+ return fmt.Errorf("node has no identity token to report its catalog")
+ }
+
+ services := n.ListLocalServices(api.ServiceType_SERVICE_TYPE_UNSPECIFIED)
+ if err := ReportNodeCatalog(ctx, controlPlaneURL, token, services); err != nil {
+ return fmt.Errorf("failed to report node catalog: %w", err)
+ }
+ return nil
+}
+
+// startCatalogReportLoop reports the local catalog once after initialDelay
+// and then every interval, each wait stretched by up to a tenth of interval
+// so a fleet started together does not hit the control plane in lockstep.
+// A failure is logged at Warn once and at Debug while it persists: the
+// usual causes (control plane unreachable, path not routed) do not change
+// from one tick to the next.
+func (n *SamNode) startCatalogReportLoop(ctx context.Context, initialDelay, interval time.Duration) {
+ if interval <= 0 {
+ interval = 1 * time.Minute
+ }
+ if initialDelay <= 0 {
+ initialDelay = 5 * time.Second
+ }
+
+ go func() {
+ wait := initialDelay
+ failures := 0
+ for {
+ timer := time.NewTimer(wait + time.Duration(rand.Int63n(int64(interval/10)+1)))
+ select {
+ case <-ctx.Done():
+ timer.Stop()
+ return
+ case <-timer.C:
+ }
+ wait = interval
+
+ err := n.reportNodeCatalog(ctx)
+ switch {
+ case err != nil && failures == 0:
+ logger.Warnf("Node catalog report failed: %v", err)
+ case err != nil:
+ logger.Debugf("Node catalog report still failing (%d consecutive): %v", failures+1, err)
+ case failures > 0:
+ logger.Infof("Node catalog report recovered after %d failures", failures)
+ }
+ if err != nil {
+ failures++
+ } else {
+ failures = 0
+ }
+ }
+ }()
+}
+
func (n *SamNode) startPolicySyncLoop(ctx context.Context, interval time.Duration) {
if interval <= 0 {
interval = 1 * time.Hour
diff --git a/internal/node/options.go b/internal/node/options.go
index 730ecd1e..dbc5e30e 100644
--- a/internal/node/options.go
+++ b/internal/node/options.go
@@ -86,6 +86,16 @@ type Options struct {
// is tight enough that even simple interpreted-language MCP servers can
// miss it on first spawn.
BackendProbeTimeout time.Duration
+ // CatalogReportInterval specifies how often the node self-reports its
+ // locally registered services to the control plane (POST
+ // /nodes/catalog), so an admin can see mesh-wide service topology
+ // without the control plane needing DHT/P2P access to every node
+ // itself. Zero uses the default.
+ CatalogReportInterval time.Duration
+ // CatalogReportInitialDelay is how long after Start the first catalog
+ // report is sent, so services configured at startup have registered by
+ // then. Zero uses the default.
+ CatalogReportInitialDelay time.Duration
}
// Default applies default values to Options if they are not specified.
@@ -136,6 +146,12 @@ func (o *Options) Default() {
if o.PolicySyncInterval == 0 {
o.PolicySyncInterval = 1 * time.Hour
}
+ if o.CatalogReportInterval <= 0 {
+ o.CatalogReportInterval = 1 * time.Minute
+ }
+ if o.CatalogReportInitialDelay <= 0 {
+ o.CatalogReportInitialDelay = 5 * time.Second
+ }
if o.PolicySyncJitter <= 0 {
o.PolicySyncJitter = 10 * time.Second
}
diff --git a/site/content/docs/user/control-plane-configuration.md b/site/content/docs/user/control-plane-configuration.md
index 3792bd4c..ffabae5f 100644
--- a/site/content/docs/user/control-plane-configuration.md
+++ b/site/content/docs/user/control-plane-configuration.md
@@ -203,7 +203,19 @@ Administrators can immediately revoke any active session to disable a node's abi
---
-## 6. Headless Node Enrollment (Bootstrap Token Flow)
+## 6. Node Service Catalog
+
+Each enrolled node periodically self-reports its locally registered services so the admin console's **Services** view can show what is running where, without the Control Plane joining the P2P mesh.
+
+* **Endpoint**: `POST /nodes/catalog`
+* **Authentication**: The node's own Biscuit as a `Bearer` token. The reporting peer is taken from the verified token, never from the body, so a node can only ever describe itself; reports from banned or expired enrollments are rejected.
+* **Payload**: An `api.NodeCatalogReport` protobuf (`application/x-protobuf`) with up to 512 services per report.
+* **Cadence**: Every minute by default (`node.Options.CatalogReportInterval`), with jitter.
+* **Semantics**: A live-status cache, not authoritative state. It is display-only and never feeds authorization; the cache is in-memory and rebuilt by the nodes' next reports after a Control Plane restart. If you front the Control Plane with a Gateway allow-list, `/nodes/catalog` must be routed like the other node-facing endpoints.
+
+---
+
+## 7. Headless Node Enrollment (Bootstrap Token Flow)
To enroll a headless server, router, or background daemon that cannot complete interactive OIDC authentication, SAM supports a **Bootstrap Token** flow.
diff --git a/tests/ui/console.spec.js b/tests/ui/console.spec.js
index ea2950fe..0d44af25 100644
--- a/tests/ui/console.spec.js
+++ b/tests/ui/console.spec.js
@@ -312,3 +312,85 @@ test('the served markup carries no inline style attribute', async ({ request })
const html = await (await request.get('/index.html')).text();
expect(html).not.toMatch(/<[^>]+\sstyle=/);
});
+
+// The Services view has no admin flow to seed it from the browser alone (a
+// real node has to self-report), so this only pins what is reachable without
+// one: the nav item routes there and the empty state renders without a JS
+// error. TestHandleNodeCatalog in internal/controlplane covers the reporting
+// endpoint itself, and TestReportNodeCatalog in internal/node covers the
+// node-side push.
+test('the Services view is reachable and renders its empty state', async ({ page }) => {
+ await login(page);
+
+ await page.click('.nav-item[data-target="services"]');
+ await expect(page).toHaveURL(/#services$/);
+ await expect(page.locator('#view-services')).toBeVisible();
+ await expect(page.locator('#table-services')).toContainText('No nodes have reported any services yet');
+});
+
+// A reload must survive on this view too, same as the other deep-linkable
+// views already covered above for #routers.
+test('the Services view is deep-linkable via the URL hash', async ({ page }) => {
+ await login(page);
+
+ await page.goto('/#services');
+ await expect(page.locator('#view-services')).toBeVisible();
+ await expect(page.locator('.nav-item[data-target="services"]')).toHaveAttribute('aria-current', 'page');
+});
+
+// Seeding the Services view for real needs an enrolled node self-reporting, so
+// render it from an intercepted /admin/status instead: the real response with
+// node_catalog and a labelled node spliced in, shaped exactly like
+// catalogViewFor in internal/controlplane/catalog.go emits it.
+test('reported services render with type, labels and report time', async ({ page }) => {
+ const PEER = '12D3KooWServicesViewFixturePeer';
+ await page.route('**/api/admin/status', async (route) => {
+ const response = await route.fetch();
+ const status = await response.json();
+ status.enrolled_nodes = [...(status.enrolled_nodes || []), {
+ PeerID: PEER,
+ Role: 'sam:role:node',
+ OwnerID: 'root-admin',
+ Labels: { component: 'stvv', region: 'eu-west' },
+ }];
+ status.node_catalog = {
+ [PEER]: {
+ services: [
+ { name: 'compliance-docs', type: 'mcp', description: 'doc lookup' },
+ // Reported names and descriptions are node-controlled input to an
+ // admin page; markup in them must render inert.
+ { name: 'llama', type: 'inference', description: '
' },
+ ],
+ reported_at: '2026-09-15T08:00:00Z',
+ },
+ };
+ await route.fulfill({ response, json: status });
+ });
+
+ await login(page);
+ await page.click('.nav-item[data-target="services"]');
+
+ const rows = page.locator('#table-services tr');
+ await expect(rows).toHaveCount(2);
+
+ const first = rows.nth(0);
+ await expect(first).toContainText('compliance-docs');
+ await expect(first).toContainText('mcp');
+ await expect(first).toContainText('doc lookup');
+ await expect(first).toContainText(PEER);
+ // The node's labels ride along as the mnemonic under the peer ID.
+ await expect(first.locator('.cell-subtext')).toHaveText('component=stvv, region=eu-west');
+ // reported_at renders as a local time, not the raw RFC 3339 string.
+ await expect(first.locator('td').nth(4)).not.toHaveText(/2026-09-15T08:00:00Z|-/);
+
+ await expect(rows.nth(1)).toContainText('inference');
+ // The description shows as text; nothing was injected into the DOM.
+ await expect(rows.nth(1)).toContainText('onerror');
+ expect(await page.locator('#table-services img').count()).toBe(0);
+ expect(await page.evaluate(() => window.svcXSS)).toBeUndefined();
+
+ // The same labels also annotate the peer ID in the Nodes table.
+ await page.click('.nav-item[data-target="nodes"]');
+ const nodeRow = page.locator('#table-nodes tr', { hasText: PEER });
+ await expect(nodeRow.locator('.cell-subtext')).toHaveText('component=stvv, region=eu-west');
+});