Merge pull request #1 from ericbrisrubio/feature/Adding-secure-verification-methods

Adding methods for signature verification

Author: ericbrisrubio

README.md

@@ -7,6 +7,7 @@ A Go SDK client for interacting with the messages-worker service. This SDK provi
 - **Message Operations**: Submit single or bulk messages with different priorities
 - **Worker Management**: Monitor and scale workers dynamically
 - **Health Checks**: Check service health and availability
+- **Callback Signature Verification**: Verify HMAC-SHA256 signatures for secure callback handling
 - **Error Handling**: Comprehensive error handling with custom error types
 - **Context Support**: Full context.Context support for timeouts and cancellation
 - **Type Safety**: Strongly typed API with proper validation
@@ -248,11 +249,70 @@ defer cancel()
 resp, err := client.PostMessage(ctx, messageReq)
 ```
 
+## Callback Signature Verification
+
+The messages-worker can generate HMAC-SHA256 signatures for callback requests. Use the SDK to verify these signatures:
+
+```go
+import (
+    "io"
+    "github.com/ericbrisrubio/messages-worker-sdk"
+)
+
+func handleCallback(w http.ResponseWriter, r *http.Request) {
+    secret := os.Getenv("CALLBACK_SECRET")
+    
+    // Read the request body
+    body, err := io.ReadAll(r.Body)
+    if err != nil {
+        log.Printf("Failed to read request body: %v", err)
+        http.Error(w, "Failed to read request body", http.StatusBadRequest)
+        return
+    }
+    
+    // Get signature from header
+    signature := r.Header.Get(sdk.GetSignatureHeader())
+    
+    // Verify signature
+    valid, err := sdk.VerifyCallbackSignature(body, signature, secret)
+    if err != nil {
+        log.Printf("Signature verification error: %v", err)
+        http.Error(w, "Signature verification failed", http.StatusUnauthorized)
+        return
+    }
+    if !valid {
+        log.Printf("Invalid signature")
+        http.Error(w, "Invalid signature", http.StatusUnauthorized)
+        return
+    }
+    
+    // Process callback...
+    log.Println("Signature verified successfully")
+}
+```
+
+### Signature Header
+
+The messages-worker sends signatures in the `X-Callback-Signature` header:
+
+```
+X-Callback-Signature: <hmac-sha256-hex-signature>
+```
+
+### Configuration
+
+Set the `CALLBACK_SECRET` environment variable in your messages-worker configuration:
+
+```bash
+export CALLBACK_SECRET="your-secret-key-here"
+```
+
 ## Examples
 
 See the `examples/` directory for complete working examples:
 
 - `examples/main.go`: Comprehensive example showing all SDK features
+- `examples/callback_handler.go`: Complete callback handler with signature verification
 
 ## API Reference
 

examples/callback-handler/main.go

@@ -0,0 +1,92 @@
+package main
+
+import (
+	"encoding/json"
+	"io"
+	"log"
+	"net/http"
+	"os"
+
+	"github.com/ericbrisrubio/messages-worker-sdk"
+)
+
+// CallbackHandler handles incoming callbacks from messages-worker
+type CallbackHandler struct {
+	secret string
+}
+
+// NewCallbackHandler creates a new callback handler
+func NewCallbackHandler(secret string) *CallbackHandler {
+	return &CallbackHandler{
+		secret: secret,
+	}
+}
+
+// HandleCallback processes incoming callback requests
+func (h *CallbackHandler) HandleCallback(w http.ResponseWriter, r *http.Request) {
+	// Read the request body
+	body, err := io.ReadAll(r.Body)
+	if err != nil {
+		log.Printf("Failed to read request body: %v", err)
+		http.Error(w, "Failed to read request body", http.StatusBadRequest)
+		return
+	}
+
+	// Verify signature if secret is configured
+	if h.secret != "" {
+		signature := r.Header.Get(sdk.GetSignatureHeader())
+		valid := sdk.VerifySignatureSha256(body, signature, h.secret)
+		if !valid {
+			log.Printf("Invalid signature")
+			http.Error(w, "Invalid signature", http.StatusUnauthorized)
+			return
+		}
+		log.Printf("Signature verified successfully")
+	}
+
+	// Parse the message
+	var message map[string]interface{}
+	if err := json.Unmarshal(body, &message); err != nil {
+		log.Printf("Failed to decode message: %v", err)
+		http.Error(w, "Invalid JSON", http.StatusBadRequest)
+		return
+	}
+
+	// Process the message
+	log.Printf("Received callback message: %+v", message)
+
+	// Return success response
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(http.StatusOK)
+	json.NewEncoder(w).Encode(map[string]string{
+		"status":  "success",
+		"message": "Callback processed successfully",
+	})
+}
+
+func main() {
+	// Get callback secret from environment
+	secret := os.Getenv("CALLBACK_SECRET")
+	if secret == "" {
+		log.Println("Warning: CALLBACK_SECRET not set, callbacks will not be verified")
+	}
+
+	// Create callback handler
+	handler := NewCallbackHandler(secret)
+
+	// Setup routes
+	http.HandleFunc("/callback", handler.HandleCallback)
+	http.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte("OK"))
+	})
+
+	// Start server
+	port := os.Getenv("PORT")
+	if port == "" {
+		port = "8080"
+	}
+
+	log.Printf("Starting callback server on port %s", port)
+	log.Fatal(http.ListenAndServe(":"+port, nil))
+}

signature.go

@@ -0,0 +1,34 @@
+package sdk
+
+import (
+	"crypto/hmac"
+	"crypto/sha256"
+	"encoding/hex"
+	"strings"
+)
+
+// VerifyCallbackSignature verifies the callback signature using HMAC-SHA256
+func VerifySignatureSha256(payload []byte, signature string, webhookSecret string) bool {
+	if signature == "" {
+		return false
+	}
+
+	// Remove "sha256=" prefix if present
+	signature = strings.TrimPrefix(signature, "sha256=")
+
+	// Create HMAC-SHA256 hash
+	mac := hmac.New(sha256.New, []byte(webhookSecret))
+	mac.Write(payload)
+	expectedMAC := mac.Sum(nil)
+
+	// Convert to hex string
+	expectedSignature := hex.EncodeToString(expectedMAC)
+
+	// Compare signatures using constant time comparison
+	return hmac.Equal([]byte(signature), []byte(expectedSignature))
+}
+
+// GetSignatureHeader returns the header name used for callback signatures
+func GetSignatureHeader() string {
+	return "X-Callback-Signature"
+}

signature_test.go

@@ -0,0 +1,87 @@
+package sdk
+
+import (
+	"crypto/hmac"
+	"crypto/sha256"
+	"encoding/hex"
+	"testing"
+)
+
+func TestVerifyCallbackSignature(t *testing.T) {
+	secret := "test-secret"
+	payload := `{"id":"test-id","item_id":"pr-123","priority":"high"}`
+
+	tests := []struct {
+		name          string
+		payload       string
+		signature     string
+		secret        string
+		expected      bool
+		expectedError bool
+	}{
+		{
+			name:          "valid signature",
+			payload:       payload,
+			signature:     generateTestSignature(payload, secret),
+			secret:        secret,
+			expected:      true,
+			expectedError: false,
+		},
+		{
+			name:          "missing signature",
+			payload:       payload,
+			signature:     "",
+			secret:        secret,
+			expected:      false,
+			expectedError: true,
+		},
+		{
+			name:          "invalid signature",
+			payload:       payload,
+			signature:     "invalidhash1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
+			secret:        secret,
+			expected:      false,
+			expectedError: false,
+		},
+		{
+			name:          "empty secret",
+			payload:       payload,
+			signature:     generateTestSignature(payload, secret),
+			secret:        "",
+			expected:      false,
+			expectedError: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := VerifySignatureSha256([]byte(tt.payload), tt.signature, tt.secret)
+
+			if tt.expectedError {
+				if result == true {
+					t.Errorf("VerifyCallbackSignature() expected error, got nil")
+				}
+				return
+			}
+
+			if result != tt.expected {
+				t.Errorf("VerifyCallbackSignature() = %v, expected %v", result, tt.expected)
+			}
+		})
+	}
+}
+
+func TestGetSignatureHeader(t *testing.T) {
+	expected := "X-Callback-Signature"
+	result := GetSignatureHeader()
+	if result != expected {
+		t.Errorf("GetSignatureHeader() = %v, expected %v", result, expected)
+	}
+}
+
+// Helper function to generate test signatures
+func generateTestSignature(payload, secret string) string {
+	mac := hmac.New(sha256.New, []byte(secret))
+	mac.Write([]byte(payload))
+	return hex.EncodeToString(mac.Sum(nil))
+}