refactor(broker): narrow health queries, add tests, fix docs

Store:
- Add ProviderHealthSummary struct and GetAllHealthStatuses() — narrow
  5-column query for /providers/health endpoint
- Add GetHealthStatus() to ProfileStorer interface
- Add rows.Err() check in GetForHealthCheck

Handler:
- Replace GetAllProfiles + manual map-building with GetAllHealthStatuses
- Fix error message grammar

Tests:
- Add GetAllHealthStatuses store tests (success, empty)
- Update Health handler tests to use new method
- Add GetAllHealthStatuses to MockProfileStorer

Docs:
- Fix duplicate section numbering (5→6) in broker.md
- Fix overstated graceful shutdown claim in healthchecks.md

Author: sangalo20

docs/healthchecks.md

@@ -152,7 +152,7 @@ Health workers run inside the standard broker process. For deployments that need
 nexus-broker --worker-only
 ```
 
-In this mode, the HTTP server does not start. The process listens for `SIGINT`/`SIGTERM` and performs a graceful shutdown, draining any in-flight checks before exiting.
+In this mode, the HTTP server does not start. The process listens for `SIGINT`/`SIGTERM` and cancels the worker context, signalling in-flight checks to stop. Note: the current implementation does not explicitly wait for worker goroutines to complete before exiting.
 
 The same Docker image and environment variables are used — just override the container command.
 

docs/services/broker.md

@@ -35,7 +35,7 @@ The Broker runs two background workers to continuously monitor integration healt
 - Both workers use bounded concurrency (semaphore + WaitGroup) to prevent goroutine exhaustion.
 - In `--worker-only` mode, the binary listens for `SIGINT`/`SIGTERM` for graceful shutdown.
 
-### 5. Audit Subsystem
+### 6. Audit Subsystem
 Every control-plane mutation is recorded in the `audit_events` table via the `audit.Service`:
 - **`provider.created`** — logged on every successful `POST /providers` call.
 - **`provider.updated`** — logged on `PUT` and `PATCH` mutations.

nexus-broker/internal/repository/postgres/connection.go

@@ -142,6 +142,10 @@ func (r *connectionRepository) GetForHealthCheck(ctx context.Context, limit int)
 		rows = append(rows, conn)
 	}
 
+	if err = dbRows.Err(); err != nil {
+		return nil, err
+	}
+
 	// Returning pointers as per interface
 	var ptrRows []*domain.ConnectionWithProvider
 	for i := range rows {

nexus-broker/internal/service/connection_test.go

@@ -165,6 +165,14 @@ func (m *MockProfileStorer) GetAllProfiles() ([]provider.Profile, error) {
 	return nil, args.Error(1)
 }
 
+func (m *MockProfileStorer) GetAllHealthStatuses() ([]provider.ProviderHealthSummary, error) {
+	args := m.Called()
+	if args.Get(0) != nil {
+		return args.Get(0).([]provider.ProviderHealthSummary), args.Error(1)
+	}
+	return nil, args.Error(1)
+}
+
 func (m *MockProfileStorer) GetMetadata() (map[string]map[string]interface{}, error) {
 	args := m.Called()
 	if args.Get(0) != nil {

nexus-broker/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: Nexus Broker API
-  version: 0.2.2
+  version: 0.2.4
   description: |
     Internal API for the Nexus Broker service. 
     This service handles OAuth 2.0 and OIDC flows, encrypts tokens, and manages provider configurations.
@@ -151,6 +151,62 @@ components:
           type: object
           description: Decrypted credentials map
           additionalProperties: true
+        health_status:
+          type: string
+          enum: [healthy, unhealthy, degraded, expired, unknown]
+          description: Current health status of the connection
+
+    ProviderHealthStatus:
+      type: object
+      properties:
+        id:
+          type: string
+          format: uuid
+        name:
+          type: string
+        health_status:
+          type: string
+          enum: [healthy, unhealthy, degraded, unknown]
+        last_health_check_at:
+          type: string
+          format: date-time
+          nullable: true
+        health_message:
+          type: string
+          description: Human-readable detail when status is not healthy
+
+    ConnectionSummary:
+      type: object
+      properties:
+        id:
+          type: string
+          format: uuid
+        provider_id:
+          type: string
+          format: uuid
+        provider_name:
+          type: string
+        auth_type:
+          type: string
+          enum: [oauth2, api_key, basic_auth]
+        status:
+          type: string
+        scopes:
+          type: array
+          items: { type: string }
+        health_status:
+          type: string
+          enum: [healthy, unhealthy, degraded, expired, unknown]
+        last_health_check_at:
+          type: string
+          format: date-time
+          nullable: true
+        created_at:
+          type: string
+          format: date-time
+        updated_at:
+          type: string
+          format: date-time
 
     MetadataResponse:
       type: object
@@ -388,6 +444,44 @@ paths:
         '404':
           description: Connection not found
 
+  /providers/health:
+    get:
+      summary: Get health status of all providers
+      description: Returns the current health status of all registered providers. No credentials are included.
+      security: [{ ApiKeyAuth: [] }]
+      responses:
+        '200':
+          description: Provider health statuses. Returns `[]` when no providers exist.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/ProviderHealthStatus'
+
+  /connections:
+    get:
+      summary: List connections for a workspace
+      description: Returns all non-pending connections for a workspace with their health status. No credentials or tokens are included.
+      security: [{ ApiKeyAuth: [] }]
+      parameters:
+        - in: query
+          name: workspace_id
+          required: true
+          schema: { type: string }
+          description: Workspace ID to filter connections by
+      responses:
+        '200':
+          description: List of connection summaries
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/ConnectionSummary'
+        '400':
+          description: Missing workspace_id parameter
+
   /connections/resolve:
     get:
       summary: Resolve and retrieve token by workspace and provider

nexus-broker/pkg/handlers/connections_test.go

@@ -0,0 +1,105 @@
+package handlers
+
+import (
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/google/uuid"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/mock"
+
+	"github.com/Prescott-Data/nexus-framework/nexus-broker/internal/domain"
+)
+
+func TestConnectionsList_Success(t *testing.T) {
+	mockSvc := new(MockConnectionService)
+	handler := NewConnectionsHandler(mockSvc)
+
+	now := time.Now()
+	expected := []domain.ConnectionSummary{
+		{
+			ID:           uuid.New(),
+			ProviderID:   uuid.New(),
+			ProviderName: "google",
+			AuthType:     "oauth2",
+			Status:       "active",
+			Scopes:       []string{"email", "calendar.read"},
+			HealthStatus: "healthy",
+			CreatedAt:    now,
+			UpdatedAt:    now,
+		},
+		{
+			ID:           uuid.New(),
+			ProviderID:   uuid.New(),
+			ProviderName: "stripe",
+			AuthType:     "api_key",
+			Status:       "active",
+			HealthStatus: "unhealthy",
+			CreatedAt:    now,
+			UpdatedAt:    now,
+		},
+	}
+
+	mockSvc.On("ListConnections", mock.Anything, "ws-123").Return(expected, nil).Once()
+
+	req := httptest.NewRequest("GET", "/connections?workspace_id=ws-123", nil)
+	rr := httptest.NewRecorder()
+
+	handler.List(rr, req)
+
+	assert.Equal(t, http.StatusOK, rr.Code)
+	assert.Contains(t, rr.Body.String(), "google")
+	assert.Contains(t, rr.Body.String(), "stripe")
+	assert.Contains(t, rr.Body.String(), `"health_status":"healthy"`)
+	assert.Contains(t, rr.Body.String(), `"health_status":"unhealthy"`)
+	mockSvc.AssertExpectations(t)
+}
+
+func TestConnectionsList_EmptyResult(t *testing.T) {
+	mockSvc := new(MockConnectionService)
+	handler := NewConnectionsHandler(mockSvc)
+
+	mockSvc.On("ListConnections", mock.Anything, "ws-empty").Return([]domain.ConnectionSummary{}, nil).Once()
+
+	req := httptest.NewRequest("GET", "/connections?workspace_id=ws-empty", nil)
+	rr := httptest.NewRecorder()
+
+	handler.List(rr, req)
+
+	assert.Equal(t, http.StatusOK, rr.Code)
+	assert.Equal(t, "[]", rr.Body.String())
+	mockSvc.AssertExpectations(t)
+}
+
+func TestConnectionsList_MissingWorkspaceID(t *testing.T) {
+	mockSvc := new(MockConnectionService)
+	handler := NewConnectionsHandler(mockSvc)
+
+	req := httptest.NewRequest("GET", "/connections", nil)
+	rr := httptest.NewRecorder()
+
+	handler.List(rr, req)
+
+	assert.Equal(t, http.StatusBadRequest, rr.Code)
+	assert.Contains(t, rr.Body.String(), "missing_workspace_id")
+	// Service should never be called
+	mockSvc.AssertNotCalled(t, "ListConnections")
+}
+
+func TestConnectionsList_ServiceError(t *testing.T) {
+	mockSvc := new(MockConnectionService)
+	handler := NewConnectionsHandler(mockSvc)
+
+	mockSvc.On("ListConnections", mock.Anything, "ws-broken").Return(nil, errors.New("database unreachable")).Once()
+
+	req := httptest.NewRequest("GET", "/connections?workspace_id=ws-broken", nil)
+	rr := httptest.NewRecorder()
+
+	handler.List(rr, req)
+
+	assert.Equal(t, http.StatusInternalServerError, rr.Code)
+	mockSvc.AssertExpectations(t)
+}

nexus-broker/pkg/handlers/providers.go

@@ -205,24 +205,13 @@ func (h *ProvidersHandler) List(w http.ResponseWriter, r *http.Request) {
 
 // Health handles GET /providers/health to list provider health statuses
 func (h *ProvidersHandler) Health(w http.ResponseWriter, r *http.Request) {
-	profiles, err := h.store.GetAllProfiles()
+	summaries, err := h.store.GetAllHealthStatuses()
 	if err != nil {
-		httputil.WriteError(w, http.StatusInternalServerError, "health_failed", "Failed to list providers health")
+		httputil.WriteError(w, http.StatusInternalServerError, "health_failed", "Failed to retrieve provider health statuses")
 		return
 	}
-	
-	healthData := make([]map[string]interface{}, 0, len(profiles))
-	for _, p := range profiles {
-		healthData = append(healthData, map[string]interface{}{
-			"id": p.ID.String(),
-			"name": p.Name,
-			"health_status": p.HealthStatus,
-			"last_health_check_at": p.LastHealthCheckAt,
-			"health_message": p.HealthMessage,
-		})
-	}
 
-	httputil.WriteJSON(w, http.StatusOK, healthData)
+	httputil.WriteJSON(w, http.StatusOK, summaries)
 }
 
 // GetByName handles GET /providers/by-name/{name}

nexus-broker/pkg/handlers/providers_test.go

@@ -8,6 +8,7 @@ import (
 	"net/http"
 	"net/http/httptest"
 	"testing"
+	"time"
 
 	"github.com/google/uuid"
 	"github.com/stretchr/testify/assert"
@@ -83,6 +84,14 @@ func (m *MockStore) GetAllProfiles() ([]provider.Profile, error) {
 	return args.Get(0).([]provider.Profile), args.Error(1)
 }
 
+func (m *MockStore) GetAllHealthStatuses() ([]provider.ProviderHealthSummary, error) {
+	args := m.Called()
+	if args.Get(0) == nil {
+		return nil, args.Error(1)
+	}
+	return args.Get(0).([]provider.ProviderHealthSummary), args.Error(1)
+}
+
 func (m *MockStore) GetMetadata() (map[string]map[string]interface{}, error) {
 	args := m.Called()
 	if args.Get(0) == nil {
@@ -278,3 +287,74 @@ func TestPatchProvider_AuditRedactsSecrets(t *testing.T) {
 		return true
 	}), mock.AnythingOfType("*http.Request"))
 }
+
+func TestHealth_Success(t *testing.T) {
+	mockStore := new(MockStore)
+	handler := NewProvidersHandler(mockStore, nil)
+
+	now := time.Now()
+	msg := "token_url returned 503"
+	summaries := []provider.ProviderHealthSummary{
+		{
+			ID:                uuid.New(),
+			Name:              "google",
+			HealthStatus:      "healthy",
+			LastHealthCheckAt: &now,
+			HealthMessage:     nil,
+		},
+		{
+			ID:                uuid.New(),
+			Name:              "stripe",
+			HealthStatus:      "unhealthy",
+			LastHealthCheckAt: &now,
+			HealthMessage:     &msg,
+		},
+	}
+
+	mockStore.On("GetAllHealthStatuses").Return(summaries, nil).Once()
+
+	req := httptest.NewRequest("GET", "/providers/health", nil)
+	rr := httptest.NewRecorder()
+
+	handler.Health(rr, req)
+
+	assert.Equal(t, http.StatusOK, rr.Code)
+	assert.Contains(t, rr.Body.String(), `"health_status":"healthy"`)
+	assert.Contains(t, rr.Body.String(), `"health_status":"unhealthy"`)
+	assert.Contains(t, rr.Body.String(), `"health_message":"token_url returned 503"`)
+	assert.Contains(t, rr.Body.String(), "google")
+	assert.Contains(t, rr.Body.String(), "stripe")
+	mockStore.AssertExpectations(t)
+}
+
+func TestHealth_EmptyList(t *testing.T) {
+	mockStore := new(MockStore)
+	handler := NewProvidersHandler(mockStore, nil)
+
+	mockStore.On("GetAllHealthStatuses").Return([]provider.ProviderHealthSummary{}, nil).Once()
+
+	req := httptest.NewRequest("GET", "/providers/health", nil)
+	rr := httptest.NewRecorder()
+
+	handler.Health(rr, req)
+
+	assert.Equal(t, http.StatusOK, rr.Code)
+	assert.Equal(t, "[]", rr.Body.String())
+	mockStore.AssertExpectations(t)
+}
+
+func TestHealth_StoreError(t *testing.T) {
+	mockStore := new(MockStore)
+	handler := NewProvidersHandler(mockStore, nil)
+
+	mockStore.On("GetAllHealthStatuses").Return(nil, errors.New("connection refused")).Once()
+
+	req := httptest.NewRequest("GET", "/providers/health", nil)
+	rr := httptest.NewRecorder()
+
+	handler.Health(rr, req)
+
+	assert.Equal(t, http.StatusInternalServerError, rr.Code)
+	assert.Contains(t, rr.Body.String(), "health_failed")
+	mockStore.AssertExpectations(t)
+}

nexus-broker/pkg/provider/interfaces.go

@@ -23,5 +23,6 @@ type ProfileStorer interface {
 	DeleteProfileByName(name string) (int64, error)
 	ListProfiles() ([]ProfileList, error)
 	GetAllProfiles() ([]Profile, error)
+	GetAllHealthStatuses() ([]ProviderHealthSummary, error)
 	GetMetadata() (map[string]map[string]interface{}, error)
 }