Skip to content

Agent Mesh

controlplane: require proof of possession on GET /enroll/status

Antonio Ojeac7864849e11b
diff --git a/api/network.go b/api/network.go
index 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.go
index 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.proto
index 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 APPROVED
diff --git a/internal/controlplane/server.go b/internal/controlplane/server.go
index 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 renewal
expiresAt := 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.BootstrapEnrollResponse
if 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.go
index 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.go
index 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, b
u = 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, b
case <-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.go
index 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.md
index 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 Revocation
Administrators can immediately revoke any active session to disable a node's ability to renew its token.