feat: add crypto package for AES-GCM and bcrypt, and implement EchoErrorHandler adapter for global error handling

Author: MichaelAndish

README.md

@@ -8,6 +8,7 @@ Each package is designed to be tightly scoped with minimal dependencies across p
 
 - **[config](./config/)**: Environment and File-based generic configuration loading.
 - **[api](./api/)**: Helper structs and utilities for the [Echo web framework](https://echo.labstack.com) (extensible to other frameworks like Chi/Gin).
+- **[crypto](./crypto/)**: Generic AES-256-GCM authenticated encryption and BCrypt credential hashing.
 - **[httperr](./httperr/)**: Structured and actionable error types for web APIs (`ServiceError`).
 - **[logger](./logger/)**: Generic JSON/text logger wrapping `log/slog` with Context extractors and multi-handler fan out.
 - **[pgsql](./pgsql/)**: Configurable PostgreSQL connection helpers with transaction context wrappers.

api/README.md

@@ -19,10 +19,7 @@ func main() {
     e := echo.New()
 
     // Set our standard error handler
-    errorHandler := api.NewEchoErrorHandler(slog.Default())
-    e.HTTPErrorHandler = func(err error, c echo.Context) {
-        errorHandler.HandleError(c, err, "request")
-    }
+    e.HTTPErrorHandler = api.NewEchoErrorHandler(slog.Default()).EchoHandler
 
     // Register routes safely
     routes := []api.EchoRouteConfig{

api/echo_router.go

@@ -8,6 +8,7 @@ package api
 import (
 	"encoding/json"
 	"errors"
+	"fmt"
 	"io"
 	"log/slog"
 
@@ -65,6 +66,23 @@ func (h *EchoErrorHandler) HandleError(c echo.Context, err error, operation stri
 	return c.JSON(httperr.StatusInternalServer, httperr.ErrInternalServer)
 }
 
+// EchoHandler adapts EchoErrorHandler to echo.HTTPErrorHandler for global registration.
+// It uses "http_request" as the default operation context.
+func (h *EchoErrorHandler) EchoHandler(err error, c echo.Context) {
+	// If the response was already committed, we shouldn't send another JSON
+	if c.Response().Committed {
+		return
+	}
+	// Echo's default error maps like 404 and 405 are returned as *echo.HTTPError
+	var he *echo.HTTPError
+	if errors.As(err, &he) {
+		_ = c.JSON(he.Code, httperr.NewServiceError(he.Code, fmt.Sprintf("%v", he.Message)))
+		return
+	}
+
+	_ = h.HandleError(c, err, "http_request")
+}
+
 // EchoUnescapedHTMLJSONSerializer is a JSON serializer that disables HTML escaping.
 // Use this when returning pre-sanitized HTML content in JSON responses.
 type EchoUnescapedHTMLJSONSerializer struct{}

api/echo_router_test.go

@@ -69,6 +69,34 @@ func TestErrorHandler(t *testing.T) {
 			t.Errorf("expected 500, got %d", rec.Code)
 		}
 	})
+
+	t.Run("EchoHandler Adapter", func(t *testing.T) {
+		req := httptest.NewRequest(http.MethodGet, "/", nil)
+		rec := httptest.NewRecorder()
+		c := e.NewContext(req, rec)
+
+		// Test that basic errors fall back to 500
+		err := errors.New("fallback error")
+		handler.EchoHandler(err, c)
+
+		if rec.Code != 500 {
+			t.Errorf("expected 500, got %d", rec.Code)
+		}
+	})
+
+	t.Run("EchoHandler Native HTTPError", func(t *testing.T) {
+		req := httptest.NewRequest(http.MethodGet, "/", nil)
+		rec := httptest.NewRecorder()
+		c := e.NewContext(req, rec)
+
+		// Test that native echo errors map accurately
+		err := echo.NewHTTPError(http.StatusNotFound, "Not Found Route")
+		handler.EchoHandler(err, c)
+
+		if rec.Code != 404 {
+			t.Errorf("expected 404, got %d", rec.Code)
+		}
+	})
 }
 
 func TestSanitizeBody(t *testing.T) {

crypto/README.md

@@ -0,0 +1,60 @@
+# crypto
+
+The `crypto` package abstracts common cryptographic operations used frequently in web services like structured AES-256-GCM authenticated encryption and BCrypt credential hashing.
+
+## Usage Example
+
+### AEAD Secret Cryptography
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/weprodev/go-pkg/crypto"
+)
+
+func main() {
+    key := []byte("0123456789abcdef0123456789abcdef") // 32 bytes required
+    
+    svc, err := crypto.NewAESService(key)
+    if err != nil {
+        panic(err)
+    }
+
+    raw := []byte("highly sensitive internal data")
+    
+    cipher, _ := svc.Encrypt(raw)
+    fmt.Printf("Encrypted safely: %x\n", cipher)
+
+    // And reverse to use it...
+    plain, _ := svc.Decrypt(cipher)
+    fmt.Println(string(plain))
+}
+```
+
+### Credential Hashing
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/weprodev/go-pkg/crypto"
+)
+
+func main() {
+    password := "my_admin_password!"
+    
+    // Automatic bcrypt salt & hash (Cost: 14)
+    hash, _ := crypto.HashSecret(password)
+
+    if crypto.CheckSecretHash("wrong", hash) {
+        fmt.Println("This string is never printed.")
+    }
+
+    if crypto.CheckSecretHash(password, hash) {
+        fmt.Println("Success!")
+    }
+}
+```

crypto/aes.go

@@ -0,0 +1,62 @@
+package crypto
+
+import (
+	"crypto/aes"
+	"crypto/cipher"
+	"crypto/rand"
+	"errors"
+	"io"
+)
+
+// AESService provides AES-256-GCM encryption for secrets.
+type AESService struct {
+	key []byte
+}
+
+// NewAESService creates a new AESService. Key must be exactly 32 bytes.
+func NewAESService(key []byte) (*AESService, error) {
+	if len(key) != 32 {
+		return nil, errors.New("AES-256 requires a 32-byte key")
+	}
+	return &AESService{key: key}, nil
+}
+
+// Encrypt encrypts the plaintext using AES-GCM.
+func (s *AESService) Encrypt(plaintext []byte) ([]byte, error) {
+	block, err := aes.NewCipher(s.key)
+	if err != nil {
+		return nil, err
+	}
+
+	gcm, err := cipher.NewGCM(block)
+	if err != nil {
+		return nil, err
+	}
+
+	nonce := make([]byte, gcm.NonceSize())
+	if _, err := io.ReadFull(rand.Reader, nonce); err != nil {
+		return nil, err
+	}
+
+	return gcm.Seal(nonce, nonce, plaintext, nil), nil
+}
+
+// Decrypt decrypts the ciphertext using AES-GCM.
+func (s *AESService) Decrypt(ciphertext []byte) ([]byte, error) {
+	block, err := aes.NewCipher(s.key)
+	if err != nil {
+		return nil, err
+	}
+
+	gcm, err := cipher.NewGCM(block)
+	if err != nil {
+		return nil, err
+	}
+
+	if len(ciphertext) < gcm.NonceSize() {
+		return nil, errors.New("ciphertext too short")
+	}
+
+	nonce, ciphertext := ciphertext[:gcm.NonceSize()], ciphertext[gcm.NonceSize():]
+	return gcm.Open(nil, nonce, ciphertext, nil)
+}

crypto/aes_test.go

@@ -0,0 +1,59 @@
+package crypto_test
+
+import (
+	"bytes"
+	"testing"
+
+	"github.com/weprodev/go-pkg/crypto"
+)
+
+func TestAESService_Validation(t *testing.T) {
+	shortKey := []byte("short_key")
+	if _, err := crypto.NewAESService(shortKey); err == nil {
+		t.Fatal("expected error for non-32-byte key")
+	}
+
+	validKey := make([]byte, 32)
+	if _, err := crypto.NewAESService(validKey); err != nil {
+		t.Fatalf("unexpected error for 32-byte key: %v", err)
+	}
+}
+
+func TestAESService_EncryptDecrypt(t *testing.T) {
+	key := []byte("0123456789abcdef0123456789abcdef") // 32 bytes
+	svc, err := crypto.NewAESService(key)
+	if err != nil {
+		t.Fatalf("failed to create AES service: %v", err)
+	}
+
+	plaintext := []byte("hello world this is a secret")
+	ciphertext, err := svc.Encrypt(plaintext)
+	if err != nil {
+		t.Fatalf("encryption failed: %v", err)
+	}
+
+	if bytes.Equal(plaintext, ciphertext) {
+		t.Fatal("ciphertext should not match plaintext")
+	}
+
+	decrypted, err := svc.Decrypt(ciphertext)
+	if err != nil {
+		t.Fatalf("decryption failed: %v", err)
+	}
+
+	if !bytes.Equal(plaintext, decrypted) {
+		t.Errorf("expected %s, got %s", plaintext, decrypted)
+	}
+}
+
+func TestAESService_DecryptShortCiphertext(t *testing.T) {
+	key := []byte("0123456789abcdef0123456789abcdef")
+	svc, _ := crypto.NewAESService(key)
+
+	// Minimal GCM nonce size is 12. Providing less than that should error out safely.
+	shortData := []byte("too_short")
+	_, err := svc.Decrypt(shortData)
+	if err == nil {
+		t.Fatal("expected error decoding short ciphertext")
+	}
+}

crypto/hash.go

@@ -0,0 +1,15 @@
+package crypto
+
+import "golang.org/x/crypto/bcrypt"
+
+// HashSecret hashes a plaintext secret using bcrypt.
+func HashSecret(secret string) (string, error) {
+	bytes, err := bcrypt.GenerateFromPassword([]byte(secret), 14)
+	return string(bytes), err
+}
+
+// CheckSecretHash compares a plaintext secret with a bcrypt hash.
+func CheckSecretHash(secret, hash string) bool {
+	err := bcrypt.CompareHashAndPassword([]byte(hash), []byte(secret))
+	return err == nil
+}

crypto/hash_test.go

@@ -0,0 +1,24 @@
+package crypto_test
+
+import (
+	"testing"
+
+	"github.com/weprodev/go-pkg/crypto"
+)
+
+func TestHashAndCheckSecret(t *testing.T) {
+	secret := "super_secret_password_123!"
+
+	hash, err := crypto.HashSecret(secret)
+	if err != nil {
+		t.Fatalf("failed to hash secret: %v", err)
+	}
+
+	if crypto.CheckSecretHash("wrong_password", hash) {
+		t.Error("expected wrong password to fail check")
+	}
+
+	if !crypto.CheckSecretHash(secret, hash) {
+		t.Error("expected correct secret to pass check")
+	}
+}

go.mod

@@ -9,6 +9,7 @@ require (
 	github.com/lib/pq v1.12.1
 	github.com/microcosm-cc/bluemonday v1.0.27
 	github.com/stretchr/testify v1.11.1
+	golang.org/x/crypto v0.49.0
 	gopkg.in/yaml.v3 v3.0.1
 )
 
@@ -26,7 +27,6 @@ require (
 	github.com/pmezard/go-difflib v1.0.0 // indirect
 	github.com/valyala/bytebufferpool v1.0.0 // indirect
 	github.com/valyala/fasttemplate v1.2.2 // indirect
-	golang.org/x/crypto v0.49.0 // indirect
 	golang.org/x/net v0.51.0 // indirect
 	golang.org/x/sys v0.42.0 // indirect
 	golang.org/x/text v0.35.0 // indirect