Agent Mesh
Go a2aa2a-protocolagent-meshagentic-aiinferencemcpmeshmesh-networknetwork-securitynetworking-aip2p-network
controlplane: require proof of possession on GET /enroll/status
Antonio Ojeac7864849e11b
diff --git a/api/network.go b/api/network.goindex ec6a86bf..459b0bc3 100644--- a/api/network.go+++ b/api/network.go@@ -19,6 +19,7 @@ import ("encoding/hex""fmt""regexp"+ "strconv""strings""time"@@ -74,6 +75,16 @@ const (TokenRefreshCheckInterval = 10 * time.Minute)+// EnrollStatusChallenge is the payload a bootstrap enrollee signs to prove+// possession of the key it submitted at /enroll when polling+// GET /enroll/status: the signature travels in the `sig` query parameter+// (unpadded base64url) alongside `ts` (unix milliseconds). The domain prefix+// keeps the signature from doubling as a /refresh challenge, which signs the+// bare timestamp.+func EnrollStatusChallenge(ts int64) []byte {+ return []byte("sam:enroll-status:" + strconv.FormatInt(ts, 10))+}+// ============================================================================// SAM Custom HTTP Headers// ============================================================================diff --git a/api/sam.pb.go b/api/sam.pb.goindex b8212d3b..5e081c40 100644--- a/api/sam.pb.go+++ b/api/sam.pb.go@@ -622,6 +622,11 @@ func (x *BootstrapEnrollRequest) GetLabels() map[string]string {return nil}+// BootstrapEnrollResponse answers POST /enroll and GET /enroll/status.+// Polling GET /enroll/status requires proof of possession of the key+// submitted at /enroll: alongside `peer_id`, the caller sends the query+// parameters `ts` (unix milliseconds) and `sig` (unpadded base64url+// signature over the UTF-8 bytes of "sam:enroll-status:<ts>").type BootstrapEnrollResponse struct {state protoimpl.MessageState `protogen:"open.v1"`Status EnrollmentStatus `protobuf:"varint,1,opt,name=status,proto3,enum=sam.v1.EnrollmentStatus" json:"status,omitempty"`diff --git a/api/sam.proto b/api/sam.protoindex 14374bd6..f7886d54 100644--- a/api/sam.proto+++ b/api/sam.proto@@ -87,6 +87,11 @@ message BootstrapEnrollRequest {map<string, string> labels = 5;}+// BootstrapEnrollResponse answers POST /enroll and GET /enroll/status.+// Polling GET /enroll/status requires proof of possession of the key+// submitted at /enroll: alongside `peer_id`, the caller sends the query+// parameters `ts` (unix milliseconds) and `sig` (unpadded base64url+// signature over the UTF-8 bytes of "sam:enroll-status:<ts>").message BootstrapEnrollResponse {EnrollmentStatus status = 1;bytes biscuit_token = 2; // Populated only if APPROVEDdiff --git a/internal/controlplane/server.go b/internal/controlplane/server.goindex f9c6b2df..4e2a4a46 100644--- a/internal/controlplane/server.go+++ b/internal/controlplane/server.go@@ -30,6 +30,7 @@ import ("net""net/http""slices"+ "strconv""strings""sync""time"@@ -44,6 +45,7 @@ import (golog "github.com/ipfs/go-log/v2""github.com/libp2p/go-libp2p/core/crypto""github.com/libp2p/go-libp2p/core/peer"+ "github.com/multiformats/go-multiaddr""github.com/prometheus/client_golang/prometheus/promhttp""golang.org/x/time/rate""google.golang.org/protobuf/encoding/protojson"@@ -913,6 +915,21 @@ func (s *Server) HandleRouterLease(w http.ResponseWriter, r *http.Request) {return}+ // Advertised addresses are served verbatim to joining peers via /info and+ // /enroll: accept only well-formed multiaddrs terminating at the+ // authenticated router itself.+ for _, addrStr := range req.Addresses {+ ma, err := multiaddr.NewMultiaddr(addrStr)+ if err != nil {+ http.Error(w, "Invalid multiaddr in addresses: "+addrStr, http.StatusBadRequest)+ return+ }+ if _, last := peer.SplitAddr(ma); last != pID {+ http.Error(w, "Address does not terminate at the authenticated router: "+addrStr, http.StatusBadRequest)+ return+ }+ }+// Expose lease renewalexpiresAt := time.Now().Add(s.config.LeaseDuration)lease := &storage.RouterLease{@@ -1307,23 +1324,56 @@ func (s *Server) HandleEnroll(w http.ResponseWriter, r *http.Request) {s.writeEnrollResponse(w, resp)}+// enrollStatusChallengeMaxAge bounds the freshness window of the signed+// /enroll/status challenge, mirroring the /refresh handshake.+const enrollStatusChallengeMaxAge = 5 * time.Minute+// HandleEnrollStatus HTTP GET `/enroll/status`+//+// The approved response carries the enrollee's Biscuit, so polling requires+// proof of possession of the key submitted at /enroll: `ts` (unix+// milliseconds) and `sig` (unpadded base64url signature over+// api.EnrollStatusChallenge(ts)) must accompany `peer_id`. Every failure+// mode after the freshness check answers a uniform 401 so the endpoint is not+// a peer-ID existence oracle for anonymous callers.func (s *Server) HandleEnrollStatus(w http.ResponseWriter, r *http.Request) {if r.Method != http.MethodGet {http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)return}+ if !s.limiter.Allow() {+ http.Error(w, "Rate limit exceeded", http.StatusTooManyRequests)+ return+ }+peerID := r.URL.Query().Get("peer_id")if peerID == "" {http.Error(w, "Missing peer_id parameter", http.StatusBadRequest)return}+ ts, err := strconv.ParseInt(r.URL.Query().Get("ts"), 10, 64)+ if err != nil || ts <= 0 {+ http.Error(w, "Missing or invalid ts parameter: signed challenge required", http.StatusUnauthorized)+ return+ }+ sig, err := base64.RawURLEncoding.DecodeString(r.URL.Query().Get("sig"))+ if err != nil || len(sig) == 0 {+ http.Error(w, "Missing or invalid sig parameter: signed challenge required", http.StatusUnauthorized)+ return+ }+ challengeTime := time.UnixMilli(ts)+ now := time.Now()+ if now.Sub(challengeTime) > enrollStatusChallengeMaxAge || challengeTime.Sub(now) > enrollStatusChallengeMaxAge {+ http.Error(w, "stale or invalid challenge timestamp", http.StatusUnauthorized)+ return+ }+ctx := r.Context()enrollReq, err := s.store.GetEnrollmentRequest(ctx, peerID)if err == storage.ErrNotFound {- s.writeEnrollError(w, api.EnrollmentStatus_ENROLLMENT_STATUS_REJECTED, "Enrollment request not found")+ http.Error(w, "Unauthorized", http.StatusUnauthorized)return} else if err != nil {logger.Errorf("Failed to retrieve enrollment status: %v", err)@@ -1331,6 +1381,19 @@ func (s *Server) HandleEnrollStatus(w http.ResponseWriter, r *http.Request) {return}+ pubKey, err := crypto.UnmarshalPublicKey(enrollReq.PublicKey)+ if err != nil {+ logger.Errorf("Corrupted public key stored for enrollment %s: %v", peerID, err)+ http.Error(w, "Unauthorized", http.StatusUnauthorized)+ return+ }+ ok, err := pubKey.Verify(api.EnrollStatusChallenge(ts), sig)+ if err != nil || !ok {+ logger.Warnw("Enroll status challenge verification failed", "peer_id", peerID)+ http.Error(w, "Unauthorized", http.StatusUnauthorized)+ return+ }+var resp *api.BootstrapEnrollResponseif enrollReq.Status == api.EnrollmentStatus_ENROLLMENT_STATUS_APPROVED {resp, err = s.buildApprovedBootstrapEnrollResponse(ctx, enrollReq.BiscuitToken, enrollReq.ResolvedAt)diff --git a/internal/controlplane/server_test.go b/internal/controlplane/server_test.goindex e7e8d538..3286b4ea 100644--- a/internal/controlplane/server_test.go+++ b/internal/controlplane/server_test.go@@ -29,6 +29,7 @@ import ("os""path/filepath""reflect"+ "strconv""strings""sync/atomic""testing"@@ -427,6 +428,29 @@ func TestNodeAndRouterRegistrationFlow(t *testing.T) {t.Errorf("expected active routers address list %v, got %v", routerAddresses, info.RouterAddresses)}+ // 5b. Leases that would redirect joiners are refused: malformed+ // multiaddrs and addresses terminating at another peer.+ for name, badAddr := range map[string]string{+ "not a multiaddr": "not-even-a-multiaddr",+ "missing p2p": "/ip4/203.0.113.66/tcp/4001",+ "foreign peer": "/ip4/203.0.113.66/tcp/4001/p2p/" + nodePeer.String(),+ } {+ badLease := &api.RouterLeaseRequest{+ PeerId: routerPeer.String(),+ Addresses: []string{badAddr},+ Biscuit: enrollRouterResp.BiscuitToken,+ }+ reqData, _ = proto.Marshal(badLease)+ resp, err = client.Post(baseURL+"/routers/lease", "application/x-protobuf", bytes.NewReader(reqData))+ if err != nil {+ t.Fatalf("POST bad lease (%s) failed: %v", name, err)+ }+ _ = resp.Body.Close()+ if resp.StatusCode != http.StatusBadRequest {+ t.Errorf("expected 400 for lease with %s, got: %s", name, resp.Status)+ }+ }+// 6. Rogue Node tries to lease as a router (lacks 'router' role)rogueLeaseReq := &api.RouterLeaseRequest{PeerId: nodePeer.String(),@@ -799,8 +823,8 @@ func TestEnrollmentWorkflow(t *testing.T) {t.Errorf("expected PENDING status, got %v", enrollResp.Status)}- // 3. Poll Enrollment Status -> PENDING- resp, err = client.Get(baseURL + "/enroll/status?peer_id=" + pID.String())+ // 3. Poll Enrollment Status -> PENDING (signed by the enrollee's key)+ resp, err = client.Get(signedEnrollStatusURL(t, baseURL, privNode, pID.String(), time.Now().UnixMilli()))if err != nil {t.Fatalf("failed to get status: %v", err)}@@ -842,7 +866,7 @@ func TestEnrollmentWorkflow(t *testing.T) {_ = resp.Body.Close()// 5. Poll Status -> APPROVED & Validate Biscuit- resp, err = client.Get(baseURL + "/enroll/status?peer_id=" + pID.String())+ resp, err = client.Get(signedEnrollStatusURL(t, baseURL, privNode, pID.String(), time.Now().UnixMilli()))if err != nil {t.Fatal(err)}@@ -925,6 +949,123 @@ func TestEnrollmentWorkflow(t *testing.T) {}}+// signedEnrollStatusURL builds a /enroll/status URL carrying the+// proof-of-possession challenge signed by priv.+func signedEnrollStatusURL(t *testing.T, baseURL string, priv crypto.PrivKey, peerID string, ts int64) string {+ t.Helper()+ sig, err := priv.Sign(api.EnrollStatusChallenge(ts))+ if err != nil {+ t.Fatalf("failed to sign enroll status challenge: %v", err)+ }+ return baseURL + "/enroll/status?peer_id=" + peerID ++ "&ts=" + strconv.FormatInt(ts, 10) ++ "&sig=" + base64.RawURLEncoding.EncodeToString(sig)+}++// TestEnrollStatusRequiresProofOfPossession pins the fix for+// GHSA-hp3x-79wr-rx66: /enroll/status must never reveal an enrollment's+// status or its biscuit to a caller that cannot sign with the key submitted+// at /enroll.+func TestEnrollStatusRequiresProofOfPossession(t *testing.T) {+ issuer, _ := startCustomMockOIDC(t)+ srv, store, baseURL := setupTestServer(t, issuer)+ defer func() {+ _ = srv.Close()+ _ = store.Close()+ }()+ srv.config.AdminToken = "super-secret-admin-token"+ srv.config.AutoApproveEnrollment = true++ client := &http.Client{Timeout: 5 * time.Second}++ adminReqBody := []byte(`{"role": "sam:role:router", "ttl_hours": 2, "max_usages": 1, "description": "PoP test"}`)+ req, _ := http.NewRequest("POST", baseURL+"/admin/bootstrap-tokens", bytes.NewBuffer(adminReqBody))+ req.Header.Set("Content-Type", "application/json")+ req.Header.Set("Authorization", "Bearer super-secret-admin-token")+ resp, err := client.Do(req)+ if err != nil {+ t.Fatalf("failed to create bootstrap token: %v", err)+ }+ var tokenDetails struct {+ Token string `json:"token"`+ }+ _ = json.NewDecoder(resp.Body).Decode(&tokenDetails)+ _ = resp.Body.Close()+ if tokenDetails.Token == "" {+ t.Fatal("empty bootstrap token")+ }++ priv, pub, err := crypto.GenerateKeyPair(crypto.Ed25519, -1)+ if err != nil {+ t.Fatal(err)+ }+ pID, _ := peer.IDFromPrivateKey(priv)+ pubBytes, _ := crypto.MarshalPublicKey(pub)++ enrollData, _ := proto.Marshal(&api.BootstrapEnrollRequest{+ BootstrapToken: tokenDetails.Token,+ PeerId: pID.String(),+ PublicKey: pubBytes,+ RequestedRole: api.RoleRouter,+ })+ resp, err = client.Post(baseURL+"/enroll", "application/x-protobuf", bytes.NewReader(enrollData))+ if err != nil {+ t.Fatalf("failed to enroll: %v", err)+ }+ body, _ := io.ReadAll(resp.Body)+ _ = resp.Body.Close()+ var enrollResp api.BootstrapEnrollResponse+ _ = proto.Unmarshal(body, &enrollResp)+ if enrollResp.Status != api.EnrollmentStatus_ENROLLMENT_STATUS_APPROVED || len(enrollResp.BiscuitToken) == 0 {+ t.Fatalf("expected auto-approved enrollment with biscuit, got %v", enrollResp.Status)+ }++ otherKey, _, err := crypto.GenerateKeyPair(crypto.Ed25519, -1)+ if err != nil {+ t.Fatal(err)+ }+ otherPID, _ := peer.IDFromPrivateKey(otherKey)++ denied := map[string]string{+ "anonymous poll": baseURL + "/enroll/status?peer_id=" + pID.String(),+ "wrong key": signedEnrollStatusURL(t, baseURL, otherKey, pID.String(), time.Now().UnixMilli()),+ "stale timestamp": signedEnrollStatusURL(t, baseURL, priv, pID.String(), time.Now().Add(-6*time.Minute).UnixMilli()),+ "unknown peer": signedEnrollStatusURL(t, baseURL, otherKey, otherPID.String(), time.Now().UnixMilli()),+ }+ for name, u := range denied {+ resp, err := client.Get(u)+ if err != nil {+ t.Fatalf("%s: request failed: %v", name, err)+ }+ body, _ := io.ReadAll(resp.Body)+ _ = resp.Body.Close()+ if resp.StatusCode != http.StatusUnauthorized {+ t.Errorf("%s: expected 401, got %s (body %q)", name, resp.Status, body)+ }+ if bytes.Contains(body, enrollResp.BiscuitToken) {+ t.Errorf("%s: response leaked the enrollment biscuit", name)+ }+ }++ // Positive control: the enrollee itself still collects its biscuit.+ resp, err = client.Get(signedEnrollStatusURL(t, baseURL, priv, pID.String(), time.Now().UnixMilli()))+ if err != nil {+ t.Fatal(err)+ }+ body, _ = io.ReadAll(resp.Body)+ _ = resp.Body.Close()+ if resp.StatusCode != http.StatusOK {+ t.Fatalf("signed poll failed: %s (body %q)", resp.Status, body)+ }+ var statusResp api.BootstrapEnrollResponse+ if err := proto.Unmarshal(body, &statusResp); err != nil {+ t.Fatalf("failed to unmarshal status response: %v", err)+ }+ if statusResp.Status != api.EnrollmentStatus_ENROLLMENT_STATUS_APPROVED || !bytes.Equal(statusResp.BiscuitToken, enrollResp.BiscuitToken) {+ t.Fatalf("signed poll did not return the approved biscuit: %v", statusResp.Status)+ }+}+// enrollRefreshTestNode enrolls a bootstrap node directly in the store and// returns its key and currently issued biscuit, ready to drive /refresh.func enrollRefreshTestNode(t *testing.T, ctx context.Context, store storage.Store) (crypto.PrivKey, []byte) {diff --git a/internal/node/enroll.go b/internal/node/enroll.goindex f3e9807b..b1c432fc 100644--- a/internal/node/enroll.go+++ b/internal/node/enroll.go@@ -18,10 +18,12 @@ import ("bytes""context""crypto/ed25519"+ "encoding/base64""fmt""io""net/http""net/url"+ "strconv""strings""time"@@ -281,8 +283,6 @@ func (n *SamNode) EnrollBootstrap(ctx context.Context, controlPlaneURL string, bu = u.JoinPath("enroll", "status")q := u.Query()q.Set("peer_id", n.Host.ID().String())- u.RawQuery = q.Encode()- statusURL := u.String()ticker := time.NewTicker(2 * time.Second)defer ticker.Stop()@@ -292,7 +292,17 @@ func (n *SamNode) EnrollBootstrap(ctx context.Context, controlPlaneURL string, bcase <-ctx.Done():return ctx.Err()case <-ticker.C:- hReq, err := http.NewRequestWithContext(ctx, http.MethodGet, statusURL, nil)+ // Prove possession of the enrollment key on every poll; the+ // control plane returns the biscuit only to the enrollee.+ ts := time.Now().UnixMilli()+ sig, err := n.config.PrivKey.Sign(api.EnrollStatusChallenge(ts))+ if err != nil {+ return fmt.Errorf("failed to sign enrollment status challenge: %w", err)+ }+ q.Set("ts", strconv.FormatInt(ts, 10))+ q.Set("sig", base64.RawURLEncoding.EncodeToString(sig))+ u.RawQuery = q.Encode()+ hReq, err := http.NewRequestWithContext(ctx, http.MethodGet, u.String(), nil)if err != nil {return fmt.Errorf("failed to create status request: %w", err)}diff --git a/internal/router/router.go b/internal/router/router.goindex d2a53be6..e70d68c3 100644--- a/internal/router/router.go+++ b/internal/router/router.go@@ -28,6 +28,7 @@ import ("os""path/filepath""runtime/debug"+ "strconv""strings""sync""sync/atomic"@@ -388,8 +389,6 @@ func (r *Router) enrollBootstrap(peerID peer.ID) error {u = u.JoinPath("enroll", "status")q := u.Query()q.Set("peer_id", peerID.String())- u.RawQuery = q.Encode()- statusURL := u.String()ticker := time.NewTicker(2 * time.Second)defer ticker.Stop()@@ -399,7 +398,17 @@ func (r *Router) enrollBootstrap(peerID peer.ID) error {case <-r.ctx.Done():return r.ctx.Err()case <-ticker.C:- req, err := http.NewRequestWithContext(r.ctx, http.MethodGet, statusURL, nil)+ // Prove possession of the enrollment key on every poll; the+ // control plane returns the biscuit only to the enrollee.+ ts := time.Now().UnixMilli()+ sig, err := r.privKey.Sign(api.EnrollStatusChallenge(ts))+ if err != nil {+ return fmt.Errorf("failed to sign enrollment status challenge: %w", err)+ }+ q.Set("ts", strconv.FormatInt(ts, 10))+ q.Set("sig", base64.RawURLEncoding.EncodeToString(sig))+ u.RawQuery = q.Encode()+ req, err := http.NewRequestWithContext(r.ctx, http.MethodGet, u.String(), nil)if err != nil {return fmt.Errorf("failed to create status request: %w", err)}diff --git a/site/content/docs/user/control-plane-configuration.md b/site/content/docs/user/control-plane-configuration.mdindex 4e2a606a..2a254eca 100644--- a/site/content/docs/user/control-plane-configuration.md+++ b/site/content/docs/user/control-plane-configuration.md@@ -171,6 +171,8 @@ Nodes and Routers run a background task that periodically checks the remaining B* **Threshold**: When the remaining token lifespan is less than 20% of its initial TTL (~4.8 hours remaining), the daemon proactively trades the expiring Biscuit for a fresh one.* **Challenge Handshake**: The client signs a current timestamp using its private key and sends it to the Control Plane `/refresh` endpoint along with its expiring Biscuit in the `Authorization: Bearer <token>` header. The Control Plane verifies the signature against the registered node's public key in the database before issuing a new Biscuit.+The bootstrap polling endpoint is guarded by the same proof of possession: `GET /enroll/status` answers only when the caller signs a current timestamp with the key it submitted at `/enroll` (sent as the `ts` and `sig` query parameters). Anything else — no signature, a stale timestamp, another key, an unknown peer — receives a uniform `401`, so an approved enrollment's Biscuit is only ever released to the enrollee itself.+### Administrative RevocationAdministrators can immediately revoke any active session to disable a node's ability to renew its token.