feat: add PoP registration, expand handleListAgents, structured errors

Phase 17 Batch 2: Proof-of-Possession verification on agent registration,
extend handleListAgents with sort/search/min_score/page_size params,
structured jsonError responses using core/errors, and refactor
validateRegisterRequest to delegate to Card.Validate().

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: gcmsg

internal/server/http.go

@@ -1,14 +1,19 @@
 package server
 
 import (
+	"bytes"
 	"context"
 	"crypto/subtle"
 	"encoding/json"
+	"io"
 	"log/slog"
 	"net/http"
+	"strconv"
 	"time"
 
 	"github.com/peerclaw/peerclaw-core/agentcard"
+	pcerrors "github.com/peerclaw/peerclaw-core/errors"
+	coreidentity "github.com/peerclaw/peerclaw-core/identity"
 	"github.com/peerclaw/peerclaw-core/protocol"
 	coresignaling "github.com/peerclaw/peerclaw-core/signaling"
 	"github.com/peerclaw/peerclaw-server/internal/audit"
@@ -453,8 +458,15 @@ type peerclawReq struct {
 }
 
 func (s *HTTPServer) handleRegister(w http.ResponseWriter, r *http.Request) {
+	// Buffer body for PoP signature verification.
+	bodyBytes, err := io.ReadAll(r.Body)
+	if err != nil {
+		s.jsonError(w, "failed to read request body", http.StatusBadRequest)
+		return
+	}
+
 	var req registerRequest
-	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+	if err := json.NewDecoder(bytes.NewReader(bodyBytes)).Decode(&req); err != nil {
 		s.jsonError(w, "invalid request body", http.StatusBadRequest)
 		return
 	}
@@ -464,6 +476,30 @@ func (s *HTTPServer) handleRegister(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
+	// Proof-of-Possession: if public_key is provided, require matching signature.
+	if req.PublicKey != "" {
+		sigHeader := r.Header.Get("X-PeerClaw-Signature")
+		pubKeyHeader := r.Header.Get("X-PeerClaw-PublicKey")
+		if sigHeader == "" || pubKeyHeader == "" {
+			s.jsonError(w, "proof-of-possession required: sign the request body with your Ed25519 key", http.StatusBadRequest)
+			return
+		}
+		if pubKeyHeader != req.PublicKey {
+			s.jsonError(w, "X-PeerClaw-PublicKey must match public_key in request body", http.StatusBadRequest)
+			return
+		}
+		// Verify signature over the raw request body.
+		pubKey, parseErr := coreidentity.ParsePublicKey(pubKeyHeader)
+		if parseErr != nil {
+			s.jsonError(w, "invalid public key: "+parseErr.Error(), http.StatusBadRequest)
+			return
+		}
+		if verifyErr := coreidentity.Verify(pubKey, bodyBytes, sigHeader); verifyErr != nil {
+			s.jsonError(w, "proof-of-possession signature verification failed", http.StatusBadRequest)
+			return
+		}
+	}
+
 	protocols := make([]protocol.Protocol, len(req.Protocols))
 	for i, p := range req.Protocols {
 		protocols[i] = protocol.Protocol(p)
@@ -522,11 +558,24 @@ func (s *HTTPServer) handleRegister(w http.ResponseWriter, r *http.Request) {
 }
 
 func (s *HTTPServer) handleListAgents(w http.ResponseWriter, r *http.Request) {
+	q := r.URL.Query()
 	filter := registry.ListFilter{
-		Protocol:   r.URL.Query().Get("protocol"),
-		Capability: r.URL.Query().Get("capability"),
-		Status:     agentcard.AgentStatus(r.URL.Query().Get("status")),
-		PageToken:  r.URL.Query().Get("page_token"),
+		Protocol:   q.Get("protocol"),
+		Capability: q.Get("capability"),
+		Status:     agentcard.AgentStatus(q.Get("status")),
+		PageToken:  q.Get("page_token"),
+		SortBy:     q.Get("sort"),
+		Search:     q.Get("search"),
+	}
+	if ms := q.Get("min_score"); ms != "" {
+		if score, err := strconv.ParseFloat(ms, 64); err == nil {
+			filter.MinScore = score
+		}
+	}
+	if ps := q.Get("page_size"); ps != "" {
+		if size, err := strconv.Atoi(ps); err == nil {
+			filter.PageSize = size
+		}
 	}
 	result, err := s.registry.ListAgents(r.Context(), filter)
 	if err != nil {
@@ -931,5 +980,26 @@ func (s *HTTPServer) jsonResponse(w http.ResponseWriter, status int, data any) {
 }
 
 func (s *HTTPServer) jsonError(w http.ResponseWriter, message string, status int) {
-	s.jsonResponse(w, status, map[string]string{"error": message})
+	code := statusToErrorCode(status)
+	s.jsonResponse(w, status, pcerrors.Error{Code: code, Message: message})
+}
+
+// statusToErrorCode maps HTTP status codes to structured error codes.
+func statusToErrorCode(status int) pcerrors.Code {
+	switch status {
+	case http.StatusNotFound:
+		return pcerrors.CodeNotFound
+	case http.StatusBadRequest:
+		return pcerrors.CodeValidation
+	case http.StatusUnauthorized, http.StatusForbidden:
+		return pcerrors.CodeAuth
+	case http.StatusConflict:
+		return pcerrors.CodeConflict
+	case http.StatusRequestTimeout, http.StatusGatewayTimeout:
+		return pcerrors.CodeTimeout
+	case http.StatusTooManyRequests:
+		return pcerrors.CodeRateLimited
+	default:
+		return pcerrors.CodeInternal
+	}
 }

internal/server/validation.go

@@ -1,22 +1,11 @@
 package server
 
 import (
-	"encoding/base64"
-	"crypto/ed25519"
 	"fmt"
-	"net/url"
-	"strings"
-	"unicode"
-)
 
-// knownProtocols are the valid protocol values for agent registration.
-var knownProtocols = map[string]bool{
-	"a2a":      true,
-	"mcp":      true,
-	"acp":      true,
-	"custom":   true,
-	"peerclaw": true,
-}
+	"github.com/peerclaw/peerclaw-core/agentcard"
+	"github.com/peerclaw/peerclaw-core/protocol"
+)
 
 // validStatuses are the valid heartbeat status values.
 var validStatuses = map[string]bool{
@@ -26,76 +15,26 @@ var validStatuses = map[string]bool{
 	"offline":  true,
 }
 
+// validateRegisterRequest validates a registration request by building a Card
+// and delegating to Card.Validate().
 func validateRegisterRequest(req *registerRequest) error {
-	// Name: 1-256 chars, no control characters.
-	if req.Name == "" {
-		return fmt.Errorf("name is required")
-	}
-	if len(req.Name) > 256 {
-		return fmt.Errorf("name must be at most 256 characters")
-	}
-	if containsControlChars(req.Name) {
-		return fmt.Errorf("name must not contain control characters")
-	}
-
-	// PublicKey: if provided, must be valid base64-encoded Ed25519 key (32 bytes).
-	if req.PublicKey != "" {
-		keyBytes, err := base64.StdEncoding.DecodeString(req.PublicKey)
-		if err != nil {
-			return fmt.Errorf("public_key must be valid base64: %w", err)
-		}
-		if len(keyBytes) != ed25519.PublicKeySize {
-			return fmt.Errorf("public_key must be %d bytes (Ed25519), got %d", ed25519.PublicKeySize, len(keyBytes))
-		}
-	}
-
-	// Capabilities: max 50 items, each ≤128 chars.
-	if len(req.Capabilities) > 50 {
-		return fmt.Errorf("capabilities must have at most 50 items")
-	}
-	for _, cap := range req.Capabilities {
-		if len(cap) > 128 {
-			return fmt.Errorf("each capability must be at most 128 characters")
-		}
-	}
-
-	// Endpoint URL: if provided, must be valid URL.
-	if req.Endpoint.URL != "" {
-		u, err := url.Parse(req.Endpoint.URL)
-		if err != nil || (u.Scheme != "http" && u.Scheme != "https") {
-			return fmt.Errorf("endpoint URL must be a valid http/https URL")
-		}
-	}
-
-	// Endpoint Port: 1-65535.
-	if req.Endpoint.Port < 0 || req.Endpoint.Port > 65535 {
-		return fmt.Errorf("endpoint port must be between 0 and 65535")
-	}
-
-	// Protocols: max 10, must be known.
-	if len(req.Protocols) > 10 {
-		return fmt.Errorf("protocols must have at most 10 items")
-	}
-	for _, p := range req.Protocols {
-		if !knownProtocols[strings.ToLower(p)] {
-			return fmt.Errorf("unknown protocol: %s", p)
-		}
-	}
-
-	// Metadata: max 50 keys, key ≤128, value ≤1024.
-	if len(req.Metadata) > 50 {
-		return fmt.Errorf("metadata must have at most 50 keys")
-	}
-	for k, v := range req.Metadata {
-		if len(k) > 128 {
-			return fmt.Errorf("metadata key must be at most 128 characters")
-		}
-		if len(v) > 1024 {
-			return fmt.Errorf("metadata value must be at most 1024 characters")
-		}
-	}
-
-	return nil
+	protocols := make([]protocol.Protocol, len(req.Protocols))
+	for i, p := range req.Protocols {
+		protocols[i] = protocol.Protocol(p)
+	}
+
+	card := &agentcard.Card{
+		Name:         req.Name,
+		PublicKey:    req.PublicKey,
+		Capabilities: req.Capabilities,
+		Endpoint: agentcard.Endpoint{
+			URL:  req.Endpoint.URL,
+			Port: req.Endpoint.Port,
+		},
+		Protocols: protocols,
+		Metadata:  req.Metadata,
+	}
+	return card.Validate()
 }
 
 func validateHeartbeatStatus(status string) error {
@@ -108,11 +47,3 @@ func validateHeartbeatStatus(status string) error {
 	return nil
 }
 
-func containsControlChars(s string) bool {
-	for _, r := range s {
-		if unicode.IsControl(r) {
-			return true
-		}
-	}
-	return false
-}