feat: M18b Filesystem Certificate Discovery — agent scanning, server dedup, triage API

Agent-side:
- Filesystem scanner walks configured directories (CERTCTL_DISCOVERY_DIRS)
- Parses PEM (.pem, .crt, .cer, .cert) and DER (.der) certificate files
- Extracts CN, SANs, serial, issuer/subject DN, validity, key info, SHA-256 fingerprint
- Reports discoveries to control plane on startup + every 6 hours
- Skips files >1MB and private key files

Server-side:
- Migration 000006: discovered_certificates + discovery_scans tables
- Domain model: DiscoveredCertificate, DiscoveryScan, DiscoveryReport
- Three triage states: Unmanaged, Managed (claimed), Dismissed
- Repository with upsert dedup (fingerprint + agent + path)
- Service layer: process reports, claim, dismiss, list, summary
- 7 new API endpoints (84 total):
  POST /agents/{id}/discoveries, GET /discovered-certificates,
  GET /discovered-certificates/{id}, POST .../claim, POST .../dismiss,
  GET /discovery-scans, GET /discovery-summary
- Audit trail: scan_completed, cert_claimed, cert_dismissed events

Tests: 28 new test functions (domain, handler, service layers)
Docs: README, quickstart, demo-guide, demo-advanced, architecture,
      concepts, connectors, features.md all updated

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

internal/api/handler/discovery.go

@@ -0,0 +1,232 @@
+package handler
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"strconv"
+
+	"github.com/shankar0123/certctl/internal/domain"
+)
+
+// DiscoveryService defines the interface used by the discovery handler.
+type DiscoveryService interface {
+	ProcessDiscoveryReport(ctx context.Context, report *domain.DiscoveryReport) (*domain.DiscoveryScan, error)
+	ListDiscovered(ctx context.Context, agentID, status string, page, perPage int) ([]*domain.DiscoveredCertificate, int, error)
+	GetDiscovered(ctx context.Context, id string) (*domain.DiscoveredCertificate, error)
+	ClaimDiscovered(ctx context.Context, id string, managedCertID string) error
+	DismissDiscovered(ctx context.Context, id string) error
+	ListScans(ctx context.Context, agentID string, page, perPage int) ([]*domain.DiscoveryScan, int, error)
+	GetScan(ctx context.Context, id string) (*domain.DiscoveryScan, error)
+	GetDiscoverySummary(ctx context.Context) (map[string]int, error)
+}
+
+// DiscoveryHandler handles HTTP requests for certificate discovery.
+type DiscoveryHandler struct {
+	svc DiscoveryService
+}
+
+// NewDiscoveryHandler creates a new discovery handler.
+func NewDiscoveryHandler(svc DiscoveryService) DiscoveryHandler {
+	return DiscoveryHandler{svc: svc}
+}
+
+// SubmitDiscoveryReport handles POST /api/v1/agents/{id}/discoveries
+// Agents submit their filesystem scan results here.
+func (h DiscoveryHandler) SubmitDiscoveryReport(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		Error(w, http.StatusMethodNotAllowed, "Method not allowed")
+		return
+	}
+
+	agentID := r.PathValue("id")
+	if agentID == "" {
+		Error(w, http.StatusBadRequest, "agent ID is required")
+		return
+	}
+
+	var report domain.DiscoveryReport
+	if err := json.NewDecoder(r.Body).Decode(&report); err != nil {
+		Error(w, http.StatusBadRequest, fmt.Sprintf("invalid request body: %v", err))
+		return
+	}
+
+	// Override agent ID from path (security: agents can only report for themselves)
+	report.AgentID = agentID
+
+	scan, err := h.svc.ProcessDiscoveryReport(r.Context(), &report)
+	if err != nil {
+		Error(w, http.StatusInternalServerError, fmt.Sprintf("failed to process discovery report: %v", err))
+		return
+	}
+
+	JSON(w, http.StatusAccepted, scan)
+}
+
+// ListDiscovered handles GET /api/v1/discovered-certificates
+func (h DiscoveryHandler) ListDiscovered(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet {
+		Error(w, http.StatusMethodNotAllowed, "Method not allowed")
+		return
+	}
+
+	query := r.URL.Query()
+	agentID := query.Get("agent_id")
+	status := query.Get("status")
+	page := parseIntDefault(query.Get("page"), 1)
+	perPage := parseIntDefault(query.Get("per_page"), 50)
+	if perPage > 500 {
+		perPage = 50
+	}
+
+	certs, total, err := h.svc.ListDiscovered(r.Context(), agentID, status, page, perPage)
+	if err != nil {
+		Error(w, http.StatusInternalServerError, fmt.Sprintf("failed to list discovered certificates: %v", err))
+		return
+	}
+
+	JSON(w, http.StatusOK, PagedResponse{
+		Data:    certs,
+		Total:   int64(total),
+		Page:    page,
+		PerPage: perPage,
+	})
+}
+
+// GetDiscovered handles GET /api/v1/discovered-certificates/{id}
+func (h DiscoveryHandler) GetDiscovered(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet {
+		Error(w, http.StatusMethodNotAllowed, "Method not allowed")
+		return
+	}
+
+	id := r.PathValue("id")
+	if id == "" {
+		Error(w, http.StatusBadRequest, "discovered certificate ID is required")
+		return
+	}
+
+	cert, err := h.svc.GetDiscovered(r.Context(), id)
+	if err != nil {
+		Error(w, http.StatusNotFound, fmt.Sprintf("discovered certificate not found: %v", err))
+		return
+	}
+
+	JSON(w, http.StatusOK, cert)
+}
+
+// ClaimDiscovered handles POST /api/v1/discovered-certificates/{id}/claim
+func (h DiscoveryHandler) ClaimDiscovered(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		Error(w, http.StatusMethodNotAllowed, "Method not allowed")
+		return
+	}
+
+	id := r.PathValue("id")
+	if id == "" {
+		Error(w, http.StatusBadRequest, "discovered certificate ID is required")
+		return
+	}
+
+	var body struct {
+		ManagedCertificateID string `json:"managed_certificate_id"`
+	}
+	if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+		Error(w, http.StatusBadRequest, fmt.Sprintf("invalid request body: %v", err))
+		return
+	}
+
+	if body.ManagedCertificateID == "" {
+		Error(w, http.StatusBadRequest, "managed_certificate_id is required")
+		return
+	}
+
+	if err := h.svc.ClaimDiscovered(r.Context(), id, body.ManagedCertificateID); err != nil {
+		Error(w, http.StatusInternalServerError, fmt.Sprintf("failed to claim certificate: %v", err))
+		return
+	}
+
+	JSON(w, http.StatusOK, map[string]string{
+		"status":  "claimed",
+		"message": "Discovered certificate linked to managed certificate",
+	})
+}
+
+// DismissDiscovered handles POST /api/v1/discovered-certificates/{id}/dismiss
+func (h DiscoveryHandler) DismissDiscovered(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		Error(w, http.StatusMethodNotAllowed, "Method not allowed")
+		return
+	}
+
+	id := r.PathValue("id")
+	if id == "" {
+		Error(w, http.StatusBadRequest, "discovered certificate ID is required")
+		return
+	}
+
+	if err := h.svc.DismissDiscovered(r.Context(), id); err != nil {
+		Error(w, http.StatusInternalServerError, fmt.Sprintf("failed to dismiss certificate: %v", err))
+		return
+	}
+
+	JSON(w, http.StatusOK, map[string]string{
+		"status":  "dismissed",
+		"message": "Discovered certificate dismissed",
+	})
+}
+
+// ListScans handles GET /api/v1/discovery-scans
+func (h DiscoveryHandler) ListScans(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet {
+		Error(w, http.StatusMethodNotAllowed, "Method not allowed")
+		return
+	}
+
+	query := r.URL.Query()
+	agentID := query.Get("agent_id")
+	page := parseIntDefault(query.Get("page"), 1)
+	perPage := parseIntDefault(query.Get("per_page"), 50)
+
+	scans, total, err := h.svc.ListScans(r.Context(), agentID, page, perPage)
+	if err != nil {
+		Error(w, http.StatusInternalServerError, fmt.Sprintf("failed to list discovery scans: %v", err))
+		return
+	}
+
+	JSON(w, http.StatusOK, PagedResponse{
+		Data:    scans,
+		Total:   int64(total),
+		Page:    page,
+		PerPage: perPage,
+	})
+}
+
+// GetDiscoverySummary handles GET /api/v1/discovery-summary
+func (h DiscoveryHandler) GetDiscoverySummary(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet {
+		Error(w, http.StatusMethodNotAllowed, "Method not allowed")
+		return
+	}
+
+	summary, err := h.svc.GetDiscoverySummary(r.Context())
+	if err != nil {
+		Error(w, http.StatusInternalServerError, fmt.Sprintf("failed to get discovery summary: %v", err))
+		return
+	}
+
+	JSON(w, http.StatusOK, summary)
+}
+
+// parseIntDefault parses an integer from a string with a default fallback.
+func parseIntDefault(s string, defaultVal int) int {
+	if s == "" {
+		return defaultVal
+	}
+	val, err := strconv.Atoi(s)
+	if err != nil || val < 1 {
+		return defaultVal
+	}
+	return val
+}

internal/api/handler/discovery_handler_test.go

@@ -0,0 +1,613 @@
+package handler
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/shankar0123/certctl/internal/api/middleware"
+	"github.com/shankar0123/certctl/internal/domain"
+	"github.com/shankar0123/certctl/internal/repository"
+)
+
+// MockDiscoveryService is a mock implementation of DiscoveryService interface.
+type MockDiscoveryService struct {
+	ProcessDiscoveryReportFn func(ctx context.Context, report *domain.DiscoveryReport) (*domain.DiscoveryScan, error)
+	ListDiscoveredFn         func(ctx context.Context, agentID, status string, page, perPage int) ([]*domain.DiscoveredCertificate, int, error)
+	GetDiscoveredFn          func(ctx context.Context, id string) (*domain.DiscoveredCertificate, error)
+	ClaimDiscoveredFn        func(ctx context.Context, id string, managedCertID string) error
+	DismissDiscoveredFn      func(ctx context.Context, id string) error
+	ListScansFn              func(ctx context.Context, agentID string, page, perPage int) ([]*domain.DiscoveryScan, int, error)
+	GetScanFn                func(ctx context.Context, id string) (*domain.DiscoveryScan, error)
+	GetDiscoverySummaryFn    func(ctx context.Context) (map[string]int, error)
+}
+
+func (m *MockDiscoveryService) ProcessDiscoveryReport(ctx context.Context, report *domain.DiscoveryReport) (*domain.DiscoveryScan, error) {
+	if m.ProcessDiscoveryReportFn != nil {
+		return m.ProcessDiscoveryReportFn(ctx, report)
+	}
+	return nil, nil
+}
+
+func (m *MockDiscoveryService) ListDiscovered(ctx context.Context, agentID, status string, page, perPage int) ([]*domain.DiscoveredCertificate, int, error) {
+	if m.ListDiscoveredFn != nil {
+		return m.ListDiscoveredFn(ctx, agentID, status, page, perPage)
+	}
+	return nil, 0, nil
+}
+
+func (m *MockDiscoveryService) GetDiscovered(ctx context.Context, id string) (*domain.DiscoveredCertificate, error) {
+	if m.GetDiscoveredFn != nil {
+		return m.GetDiscoveredFn(ctx, id)
+	}
+	return nil, nil
+}
+
+func (m *MockDiscoveryService) ClaimDiscovered(ctx context.Context, id string, managedCertID string) error {
+	if m.ClaimDiscoveredFn != nil {
+		return m.ClaimDiscoveredFn(ctx, id, managedCertID)
+	}
+	return nil
+}
+
+func (m *MockDiscoveryService) DismissDiscovered(ctx context.Context, id string) error {
+	if m.DismissDiscoveredFn != nil {
+		return m.DismissDiscoveredFn(ctx, id)
+	}
+	return nil
+}
+
+func (m *MockDiscoveryService) ListScans(ctx context.Context, agentID string, page, perPage int) ([]*domain.DiscoveryScan, int, error) {
+	if m.ListScansFn != nil {
+		return m.ListScansFn(ctx, agentID, page, perPage)
+	}
+	return nil, 0, nil
+}
+
+func (m *MockDiscoveryService) GetScan(ctx context.Context, id string) (*domain.DiscoveryScan, error) {
+	if m.GetScanFn != nil {
+		return m.GetScanFn(ctx, id)
+	}
+	return nil, nil
+}
+
+func (m *MockDiscoveryService) GetDiscoverySummary(ctx context.Context) (map[string]int, error) {
+	if m.GetDiscoverySummaryFn != nil {
+		return m.GetDiscoverySummaryFn(ctx)
+	}
+	return nil, nil
+}
+
+// Helper function to create context with request ID.
+func discoveryContextWithRequestID() context.Context {
+	return context.WithValue(context.Background(), middleware.RequestIDKey{}, "test-request-id-123")
+}
+
+// Test SubmitDiscoveryReport - success case
+func TestSubmitDiscoveryReport_Success(t *testing.T) {
+	now := time.Now()
+	scan := &domain.DiscoveryScan{
+		ID:                "dscan-1",
+		AgentID:           "agent-1",
+		CertificatesFound: 2,
+		CertificatesNew:   1,
+		ErrorsCount:       0,
+		ScanDurationMs:    150,
+		StartedAt:         now,
+		CompletedAt:       &now,
+	}
+
+	mock := &MockDiscoveryService{
+		ProcessDiscoveryReportFn: func(ctx context.Context, report *domain.DiscoveryReport) (*domain.DiscoveryScan, error) {
+			if report.AgentID == "agent-1" && len(report.Certificates) == 2 {
+				return scan, nil
+			}
+			return nil, fmt.Errorf("unexpected report")
+		},
+	}
+
+	handler := NewDiscoveryHandler(mock)
+
+	reportBody := domain.DiscoveryReport{
+		AgentID: "agent-1",
+		Certificates: []domain.DiscoveredCertEntry{
+			{
+				FingerprintSHA256: "abc123",
+				CommonName:        "example.com",
+				SerialNumber:      "001",
+				SourcePath:        "/etc/certs/example.com.crt",
+			},
+			{
+				FingerprintSHA256: "def456",
+				CommonName:        "api.example.com",
+				SerialNumber:      "002",
+				SourcePath:        "/etc/certs/api.example.com.crt",
+			},
+		},
+		ScanDurationMs: 150,
+	}
+
+	body, _ := json.Marshal(reportBody)
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/agents/agent-1/discoveries", bytes.NewReader(body))
+	req = req.WithContext(discoveryContextWithRequestID())
+	req.SetPathValue("id", "agent-1")
+	w := httptest.NewRecorder()
+
+	handler.SubmitDiscoveryReport(w, req)
+
+	if w.Code != http.StatusAccepted {
+		t.Errorf("expected status %d, got %d", http.StatusAccepted, w.Code)
+	}
+
+	var response *domain.DiscoveryScan
+	if err := json.NewDecoder(w.Body).Decode(&response); err != nil {
+		t.Fatalf("failed to decode response: %v", err)
+	}
+
+	if response.ID != "dscan-1" {
+		t.Errorf("expected scan ID dscan-1, got %s", response.ID)
+	}
+	if response.CertificatesFound != 2 {
+		t.Errorf("expected 2 certificates found, got %d", response.CertificatesFound)
+	}
+}
+
+// Test SubmitDiscoveryReport - invalid body
+func TestSubmitDiscoveryReport_InvalidBody(t *testing.T) {
+	mock := &MockDiscoveryService{}
+	handler := NewDiscoveryHandler(mock)
+
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/agents/agent-1/discoveries", bytes.NewReader([]byte("invalid json")))
+	req = req.WithContext(discoveryContextWithRequestID())
+	req.SetPathValue("id", "agent-1")
+	w := httptest.NewRecorder()
+
+	handler.SubmitDiscoveryReport(w, req)
+
+	if w.Code != http.StatusBadRequest {
+		t.Errorf("expected status %d, got %d", http.StatusBadRequest, w.Code)
+	}
+}
+
+// Test SubmitDiscoveryReport - method not allowed
+func TestSubmitDiscoveryReport_MethodNotAllowed(t *testing.T) {
+	mock := &MockDiscoveryService{}
+	handler := NewDiscoveryHandler(mock)
+
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/agents/agent-1/discoveries", nil)
+	req = req.WithContext(discoveryContextWithRequestID())
+	req.SetPathValue("id", "agent-1")
+	w := httptest.NewRecorder()
+
+	handler.SubmitDiscoveryReport(w, req)
+
+	if w.Code != http.StatusMethodNotAllowed {
+		t.Errorf("expected status %d, got %d", http.StatusMethodNotAllowed, w.Code)
+	}
+}
+
+// Test ListDiscovered - success case
+func TestListDiscovered_Success(t *testing.T) {
+	now := time.Now()
+	certs := []*domain.DiscoveredCertificate{
+		{
+			ID:           "dcert-1",
+			CommonName:   "example.com",
+			SerialNumber: "001",
+			Status:       domain.DiscoveryStatusUnmanaged,
+			CreatedAt:    now,
+			UpdatedAt:    now,
+		},
+		{
+			ID:           "dcert-2",
+			CommonName:   "api.example.com",
+			SerialNumber: "002",
+			Status:       domain.DiscoveryStatusManaged,
+			CreatedAt:    now,
+			UpdatedAt:    now,
+		},
+	}
+
+	mock := &MockDiscoveryService{
+		ListDiscoveredFn: func(ctx context.Context, agentID, status string, page, perPage int) ([]*domain.DiscoveredCertificate, int, error) {
+			if page == 1 && perPage == 50 {
+				return certs, 2, nil
+			}
+			return nil, 0, nil
+		},
+	}
+
+	handler := NewDiscoveryHandler(mock)
+
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/discovered-certificates?page=1&per_page=50", nil)
+	req = req.WithContext(discoveryContextWithRequestID())
+	w := httptest.NewRecorder()
+
+	handler.ListDiscovered(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Errorf("expected status %d, got %d", http.StatusOK, w.Code)
+	}
+
+	var response PagedResponse
+	if err := json.NewDecoder(w.Body).Decode(&response); err != nil {
+		t.Fatalf("failed to decode response: %v", err)
+	}
+
+	if response.Total != 2 {
+		t.Errorf("expected total 2, got %d", response.Total)
+	}
+}
+
+// Test ListDiscovered - with filters
+func TestListDiscovered_WithFilters(t *testing.T) {
+	mock := &MockDiscoveryService{
+		ListDiscoveredFn: func(ctx context.Context, agentID, status string, page, perPage int) ([]*domain.DiscoveredCertificate, int, error) {
+			if agentID == "agent-1" && status == "Unmanaged" {
+				return []*domain.DiscoveredCertificate{}, 0, nil
+			}
+			return nil, 0, nil
+		},
+	}
+
+	handler := NewDiscoveryHandler(mock)
+
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/discovered-certificates?agent_id=agent-1&status=Unmanaged&page=1&per_page=25", nil)
+	req = req.WithContext(discoveryContextWithRequestID())
+	w := httptest.NewRecorder()
+
+	handler.ListDiscovered(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Errorf("expected status %d, got %d", http.StatusOK, w.Code)
+	}
+}
+
+// Test ListDiscovered - method not allowed
+func TestListDiscovered_MethodNotAllowed(t *testing.T) {
+	mock := &MockDiscoveryService{}
+	handler := NewDiscoveryHandler(mock)
+
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/discovered-certificates", nil)
+	req = req.WithContext(discoveryContextWithRequestID())
+	w := httptest.NewRecorder()
+
+	handler.ListDiscovered(w, req)
+
+	if w.Code != http.StatusMethodNotAllowed {
+		t.Errorf("expected status %d, got %d", http.StatusMethodNotAllowed, w.Code)
+	}
+}
+
+// Test GetDiscovered - success case
+func TestGetDiscovered_Success(t *testing.T) {
+	now := time.Now()
+	cert := &domain.DiscoveredCertificate{
+		ID:           "dcert-1",
+		CommonName:   "example.com",
+		SerialNumber: "001",
+		Status:       domain.DiscoveryStatusUnmanaged,
+		CreatedAt:    now,
+		UpdatedAt:    now,
+	}
+
+	mock := &MockDiscoveryService{
+		GetDiscoveredFn: func(ctx context.Context, id string) (*domain.DiscoveredCertificate, error) {
+			if id == "dcert-1" {
+				return cert, nil
+			}
+			return nil, fmt.Errorf("not found")
+		},
+	}
+
+	handler := NewDiscoveryHandler(mock)
+
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/discovered-certificates/dcert-1", nil)
+	req = req.WithContext(discoveryContextWithRequestID())
+	req.SetPathValue("id", "dcert-1")
+	w := httptest.NewRecorder()
+
+	handler.GetDiscovered(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Errorf("expected status %d, got %d", http.StatusOK, w.Code)
+	}
+
+	var response *domain.DiscoveredCertificate
+	if err := json.NewDecoder(w.Body).Decode(&response); err != nil {
+		t.Fatalf("failed to decode response: %v", err)
+	}
+
+	if response.ID != "dcert-1" {
+		t.Errorf("expected ID dcert-1, got %s", response.ID)
+	}
+}
+
+// Test GetDiscovered - not found
+func TestGetDiscovered_NotFound(t *testing.T) {
+	mock := &MockDiscoveryService{
+		GetDiscoveredFn: func(ctx context.Context, id string) (*domain.DiscoveredCertificate, error) {
+			return nil, fmt.Errorf("not found")
+		},
+	}
+
+	handler := NewDiscoveryHandler(mock)
+
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/discovered-certificates/nonexistent", nil)
+	req = req.WithContext(discoveryContextWithRequestID())
+	req.SetPathValue("id", "nonexistent")
+	w := httptest.NewRecorder()
+
+	handler.GetDiscovered(w, req)
+
+	if w.Code != http.StatusNotFound {
+		t.Errorf("expected status %d, got %d", http.StatusNotFound, w.Code)
+	}
+}
+
+// Test ClaimDiscovered - success case
+func TestClaimDiscovered_Success(t *testing.T) {
+	mock := &MockDiscoveryService{
+		ClaimDiscoveredFn: func(ctx context.Context, id string, managedCertID string) error {
+			if id == "dcert-1" && managedCertID == "mc-prod-1" {
+				return nil
+			}
+			return fmt.Errorf("unexpected parameters")
+		},
+	}
+
+	handler := NewDiscoveryHandler(mock)
+
+	claimBody := map[string]string{
+		"managed_certificate_id": "mc-prod-1",
+	}
+	body, _ := json.Marshal(claimBody)
+
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/discovered-certificates/dcert-1/claim", bytes.NewReader(body))
+	req = req.WithContext(discoveryContextWithRequestID())
+	req.SetPathValue("id", "dcert-1")
+	w := httptest.NewRecorder()
+
+	handler.ClaimDiscovered(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Errorf("expected status %d, got %d", http.StatusOK, w.Code)
+	}
+
+	var response map[string]string
+	if err := json.NewDecoder(w.Body).Decode(&response); err != nil {
+		t.Fatalf("failed to decode response: %v", err)
+	}
+
+	if response["status"] != "claimed" {
+		t.Errorf("expected status 'claimed', got %s", response["status"])
+	}
+}
+
+// Test ClaimDiscovered - missing managed_certificate_id
+func TestClaimDiscovered_MissingManagedCertID(t *testing.T) {
+	mock := &MockDiscoveryService{}
+	handler := NewDiscoveryHandler(mock)
+
+	claimBody := map[string]string{}
+	body, _ := json.Marshal(claimBody)
+
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/discovered-certificates/dcert-1/claim", bytes.NewReader(body))
+	req = req.WithContext(discoveryContextWithRequestID())
+	req.SetPathValue("id", "dcert-1")
+	w := httptest.NewRecorder()
+
+	handler.ClaimDiscovered(w, req)
+
+	if w.Code != http.StatusBadRequest {
+		t.Errorf("expected status %d, got %d", http.StatusBadRequest, w.Code)
+	}
+}
+
+// Test ClaimDiscovered - discovered cert not found
+func TestClaimDiscovered_NotFound(t *testing.T) {
+	mock := &MockDiscoveryService{
+		ClaimDiscoveredFn: func(ctx context.Context, id string, managedCertID string) error {
+			return fmt.Errorf("discovered certificate not found")
+		},
+	}
+
+	handler := NewDiscoveryHandler(mock)
+
+	claimBody := map[string]string{
+		"managed_certificate_id": "mc-prod-1",
+	}
+	body, _ := json.Marshal(claimBody)
+
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/discovered-certificates/nonexistent/claim", bytes.NewReader(body))
+	req = req.WithContext(discoveryContextWithRequestID())
+	req.SetPathValue("id", "nonexistent")
+	w := httptest.NewRecorder()
+
+	handler.ClaimDiscovered(w, req)
+
+	if w.Code != http.StatusInternalServerError {
+		t.Errorf("expected status %d, got %d", http.StatusInternalServerError, w.Code)
+	}
+}
+
+// Test DismissDiscovered - success case
+func TestDismissDiscovered_Success(t *testing.T) {
+	mock := &MockDiscoveryService{
+		DismissDiscoveredFn: func(ctx context.Context, id string) error {
+			if id == "dcert-1" {
+				return nil
+			}
+			return fmt.Errorf("not found")
+		},
+	}
+
+	handler := NewDiscoveryHandler(mock)
+
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/discovered-certificates/dcert-1/dismiss", nil)
+	req = req.WithContext(discoveryContextWithRequestID())
+	req.SetPathValue("id", "dcert-1")
+	w := httptest.NewRecorder()
+
+	handler.DismissDiscovered(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Errorf("expected status %d, got %d", http.StatusOK, w.Code)
+	}
+
+	var response map[string]string
+	if err := json.NewDecoder(w.Body).Decode(&response); err != nil {
+		t.Fatalf("failed to decode response: %v", err)
+	}
+
+	if response["status"] != "dismissed" {
+		t.Errorf("expected status 'dismissed', got %s", response["status"])
+	}
+}
+
+// Test DismissDiscovered - method not allowed
+func TestDismissDiscovered_MethodNotAllowed(t *testing.T) {
+	mock := &MockDiscoveryService{}
+	handler := NewDiscoveryHandler(mock)
+
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/discovered-certificates/dcert-1/dismiss", nil)
+	req = req.WithContext(discoveryContextWithRequestID())
+	req.SetPathValue("id", "dcert-1")
+	w := httptest.NewRecorder()
+
+	handler.DismissDiscovered(w, req)
+
+	if w.Code != http.StatusMethodNotAllowed {
+		t.Errorf("expected status %d, got %d", http.StatusMethodNotAllowed, w.Code)
+	}
+}
+
+// Test ListScans - success case
+func TestListScans_Success(t *testing.T) {
+	now := time.Now()
+	scans := []*domain.DiscoveryScan{
+		{
+			ID:                "dscan-1",
+			AgentID:           "agent-1",
+			CertificatesFound: 5,
+			CertificatesNew:   2,
+			ScanDurationMs:    200,
+			StartedAt:         now,
+			CompletedAt:       &now,
+		},
+	}
+
+	mock := &MockDiscoveryService{
+		ListScansFn: func(ctx context.Context, agentID string, page, perPage int) ([]*domain.DiscoveryScan, int, error) {
+			if page == 1 && perPage == 50 {
+				return scans, 1, nil
+			}
+			return nil, 0, nil
+		},
+	}
+
+	handler := NewDiscoveryHandler(mock)
+
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/discovery-scans?page=1&per_page=50", nil)
+	req = req.WithContext(discoveryContextWithRequestID())
+	w := httptest.NewRecorder()
+
+	handler.ListScans(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Errorf("expected status %d, got %d", http.StatusOK, w.Code)
+	}
+
+	var response PagedResponse
+	if err := json.NewDecoder(w.Body).Decode(&response); err != nil {
+		t.Fatalf("failed to decode response: %v", err)
+	}
+
+	if response.Total != 1 {
+		t.Errorf("expected total 1, got %d", response.Total)
+	}
+}
+
+// Test ListScans - with agent filter
+func TestListScans_WithAgentFilter(t *testing.T) {
+	mock := &MockDiscoveryService{
+		ListScansFn: func(ctx context.Context, agentID string, page, perPage int) ([]*domain.DiscoveryScan, int, error) {
+			if agentID == "agent-1" {
+				return []*domain.DiscoveryScan{}, 0, nil
+			}
+			return nil, 0, nil
+		},
+	}
+
+	handler := NewDiscoveryHandler(mock)
+
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/discovery-scans?agent_id=agent-1", nil)
+	req = req.WithContext(discoveryContextWithRequestID())
+	w := httptest.NewRecorder()
+
+	handler.ListScans(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Errorf("expected status %d, got %d", http.StatusOK, w.Code)
+	}
+}
+
+// Test GetDiscoverySummary - success case
+func TestGetDiscoverySummary_Success(t *testing.T) {
+	summary := map[string]int{
+		"Unmanaged": 5,
+		"Managed":   3,
+		"Dismissed": 1,
+	}
+
+	mock := &MockDiscoveryService{
+		GetDiscoverySummaryFn: func(ctx context.Context) (map[string]int, error) {
+			return summary, nil
+		},
+	}
+
+	handler := NewDiscoveryHandler(mock)
+
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/discovery-summary", nil)
+	req = req.WithContext(discoveryContextWithRequestID())
+	w := httptest.NewRecorder()
+
+	handler.GetDiscoverySummary(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Errorf("expected status %d, got %d", http.StatusOK, w.Code)
+	}
+
+	var response map[string]int
+	if err := json.NewDecoder(w.Body).Decode(&response); err != nil {
+		t.Fatalf("failed to decode response: %v", err)
+	}
+
+	if response["Unmanaged"] != 5 {
+		t.Errorf("expected Unmanaged count 5, got %d", response["Unmanaged"])
+	}
+	if response["Managed"] != 3 {
+		t.Errorf("expected Managed count 3, got %d", response["Managed"])
+	}
+}
+
+// Test GetDiscoverySummary - method not allowed
+func TestGetDiscoverySummary_MethodNotAllowed(t *testing.T) {
+	mock := &MockDiscoveryService{}
+	handler := NewDiscoveryHandler(mock)
+
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/discovery-summary", nil)
+	req = req.WithContext(discoveryContextWithRequestID())
+	w := httptest.NewRecorder()
+
+	handler.GetDiscoverySummary(w, req)
+
+	if w.Code != http.StatusMethodNotAllowed {
+		t.Errorf("expected status %d, got %d", http.StatusMethodNotAllowed, w.Code)
+	}
+}

internal/api/router/router.go

@@ -60,6 +60,7 @@ func (r *Router) RegisterHandlers(
 	stats handler.StatsHandler,
 	metrics handler.MetricsHandler,
 	health handler.HealthHandler,
+	discovery handler.DiscoveryHandler,
 ) {
 	// Health endpoints (no auth middleware — must always be accessible)
 	r.mux.Handle("GET /health", middleware.Chain(
@@ -187,6 +188,15 @@ func (r *Router) RegisterHandlers(
 
 	// Metrics routes: /api/v1/metrics
 	r.Register("GET /api/v1/metrics", http.HandlerFunc(metrics.GetMetrics))
+
+	// Discovery routes: /api/v1/discovered-certificates, /api/v1/discovery-scans
+	r.Register("POST /api/v1/agents/{id}/discoveries", http.HandlerFunc(discovery.SubmitDiscoveryReport))
+	r.Register("GET /api/v1/discovered-certificates", http.HandlerFunc(discovery.ListDiscovered))
+	r.Register("GET /api/v1/discovered-certificates/{id}", http.HandlerFunc(discovery.GetDiscovered))
+	r.Register("POST /api/v1/discovered-certificates/{id}/claim", http.HandlerFunc(discovery.ClaimDiscovered))
+	r.Register("POST /api/v1/discovered-certificates/{id}/dismiss", http.HandlerFunc(discovery.DismissDiscovered))
+	r.Register("GET /api/v1/discovery-scans", http.HandlerFunc(discovery.ListScans))
+	r.Register("GET /api/v1/discovery-summary", http.HandlerFunc(discovery.GetDiscoverySummary))
 }
 
 // GetMux returns the underlying http.ServeMux for direct access if needed.