Migrate from Gin to Echo framework and add comprehensive integration tests

Major changes:
- Migrate all handlers from Gin to Echo framework
- Add new apperrors, echohelpers, and validator packages
- Update middleware for Echo compatibility
- Add ArchivedHandler to task categorization chain (archived tasks go to cancelled_tasks column)
- Add 6 new integration tests:
  - RecurringTaskLifecycle: NextDueDate advancement for weekly/monthly tasks
  - MultiUserSharing: Complex sharing with user removal
  - TaskStateTransitions: All state transitions and kanban column changes
  - DateBoundaryEdgeCases: Threshold boundary testing
  - CascadeOperations: Residence deletion cascade effects
  - MultiUserOperations: Shared residence collaboration
- Add single-purpose repository functions for kanban columns (GetOverdueTasks, GetDueSoonTasks, etc.)
- Fix RemoveUser route param mismatch (userId -> user_id)
- Fix determineExpectedColumn helper to correctly prioritize in_progress over overdue

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

internal/middleware/admin_auth.go

@@ -6,7 +6,7 @@ import (
 	"strings"
 	"time"
 
-	"github.com/gin-gonic/gin"
+	"github.com/labstack/echo/v4"
 	"github.com/golang-jwt/jwt/v5"
 
 	"github.com/treytartt/casera-api/internal/config"
@@ -30,68 +30,65 @@ type AdminClaims struct {
 }
 
 // AdminAuthMiddleware creates a middleware that validates admin JWT tokens
-func AdminAuthMiddleware(cfg *config.Config, adminRepo *repositories.AdminRepository) gin.HandlerFunc {
-	return func(c *gin.Context) {
-		var tokenString string
+func AdminAuthMiddleware(cfg *config.Config, adminRepo *repositories.AdminRepository) echo.MiddlewareFunc {
+	return func(next echo.HandlerFunc) echo.HandlerFunc {
+		return func(c echo.Context) error {
+			var tokenString string
 
-		// Get token from Authorization header
-		authHeader := c.GetHeader("Authorization")
-		if authHeader != "" {
-			// Check Bearer prefix
-			parts := strings.SplitN(authHeader, " ", 2)
-			if len(parts) == 2 && strings.ToLower(parts[0]) == "bearer" {
-				tokenString = parts[1]
+			// Get token from Authorization header
+			authHeader := c.Request().Header.Get("Authorization")
+			if authHeader != "" {
+				// Check Bearer prefix
+				parts := strings.SplitN(authHeader, " ", 2)
+				if len(parts) == 2 && strings.ToLower(parts[0]) == "bearer" {
+					tokenString = parts[1]
+				}
 			}
-		}
 
-		// If no header token, check query parameter (for WebSocket connections)
-		if tokenString == "" {
-			tokenString = c.Query("token")
-		}
-
-		if tokenString == "" {
-			c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "Authorization required"})
-			return
-		}
-
-		// Parse and validate token
-		claims := &AdminClaims{}
-		token, err := jwt.ParseWithClaims(tokenString, claims, func(token *jwt.Token) (interface{}, error) {
-			// Validate signing method
-			if _, ok := token.Method.(*jwt.SigningMethodHMAC); !ok {
-				return nil, errors.New("invalid signing method")
+			// If no header token, check query parameter (for WebSocket connections)
+			if tokenString == "" {
+				tokenString = c.QueryParam("token")
 			}
-			return []byte(cfg.Security.SecretKey), nil
-		})
 
-		if err != nil {
-			c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "Invalid token"})
-			return
+			if tokenString == "" {
+				return c.JSON(http.StatusUnauthorized, map[string]interface{}{"error": "Authorization required"})
+			}
+
+			// Parse and validate token
+			claims := &AdminClaims{}
+			token, err := jwt.ParseWithClaims(tokenString, claims, func(token *jwt.Token) (interface{}, error) {
+				// Validate signing method
+				if _, ok := token.Method.(*jwt.SigningMethodHMAC); !ok {
+					return nil, errors.New("invalid signing method")
+				}
+				return []byte(cfg.Security.SecretKey), nil
+			})
+
+			if err != nil {
+				return c.JSON(http.StatusUnauthorized, map[string]interface{}{"error": "Invalid token"})
+			}
+
+			if !token.Valid {
+				return c.JSON(http.StatusUnauthorized, map[string]interface{}{"error": "Token is not valid"})
+			}
+
+			// Get admin user from database
+			admin, err := adminRepo.FindByID(claims.AdminID)
+			if err != nil {
+				return c.JSON(http.StatusUnauthorized, map[string]interface{}{"error": "Admin user not found"})
+			}
+
+			// Check if admin is active
+			if !admin.IsActive {
+				return c.JSON(http.StatusUnauthorized, map[string]interface{}{"error": "Admin account is disabled"})
+			}
+
+			// Store admin and claims in context
+			c.Set(AdminUserKey, admin)
+			c.Set(AdminClaimsKey, claims)
+
+			return next(c)
 		}
-
-		if !token.Valid {
-			c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "Token is not valid"})
-			return
-		}
-
-		// Get admin user from database
-		admin, err := adminRepo.FindByID(claims.AdminID)
-		if err != nil {
-			c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "Admin user not found"})
-			return
-		}
-
-		// Check if admin is active
-		if !admin.IsActive {
-			c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "Admin account is disabled"})
-			return
-		}
-
-		// Store admin and claims in context
-		c.Set(AdminUserKey, admin)
-		c.Set(AdminClaimsKey, claims)
-
-		c.Next()
 	}
 }
 
@@ -116,20 +113,20 @@ func GenerateAdminToken(admin *models.AdminUser, cfg *config.Config) (string, er
 }
 
 // RequireSuperAdmin middleware requires the admin to have super_admin role
-func RequireSuperAdmin() gin.HandlerFunc {
-	return func(c *gin.Context) {
-		admin, exists := c.Get(AdminUserKey)
-		if !exists {
-			c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "Admin authentication required"})
-			return
-		}
+func RequireSuperAdmin() echo.MiddlewareFunc {
+	return func(next echo.HandlerFunc) echo.HandlerFunc {
+		return func(c echo.Context) error {
+			admin := c.Get(AdminUserKey)
+			if admin == nil {
+				return c.JSON(http.StatusUnauthorized, map[string]interface{}{"error": "Admin authentication required"})
+			}
 
-		adminUser := admin.(*models.AdminUser)
-		if !adminUser.IsSuperAdmin() {
-			c.AbortWithStatusJSON(http.StatusForbidden, gin.H{"error": "Super admin privileges required"})
-			return
-		}
+			adminUser := admin.(*models.AdminUser)
+			if !adminUser.IsSuperAdmin() {
+				return c.JSON(http.StatusForbidden, map[string]interface{}{"error": "Super admin privileges required"})
+			}
 
-		c.Next()
+			return next(c)
+		}
 	}
 }

internal/middleware/auth.go

@@ -3,15 +3,15 @@ package middleware
 import (
 	"context"
 	"fmt"
-	"net/http"
 	"strings"
 	"time"
 
-	"github.com/gin-gonic/gin"
+	"github.com/labstack/echo/v4"
 	"github.com/redis/go-redis/v9"
 	"github.com/rs/zerolog/log"
 	"gorm.io/gorm"
 
+	"github.com/treytartt/casera-api/internal/apperrors"
 	"github.com/treytartt/casera-api/internal/models"
 	"github.com/treytartt/casera-api/internal/services"
 )
@@ -41,84 +41,79 @@ func NewAuthMiddleware(db *gorm.DB, cache *services.CacheService) *AuthMiddlewar
 	}
 }
 
-// TokenAuth returns a Gin middleware that validates token authentication
-func (m *AuthMiddleware) TokenAuth() gin.HandlerFunc {
-	return func(c *gin.Context) {
-		// Extract token from Authorization header
-		token, err := extractToken(c)
-		if err != nil {
-			c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{
-				"error": err.Error(),
-			})
-			return
-		}
+// TokenAuth returns an Echo middleware that validates token authentication
+func (m *AuthMiddleware) TokenAuth() echo.MiddlewareFunc {
+	return func(next echo.HandlerFunc) echo.HandlerFunc {
+		return func(c echo.Context) error {
+			// Extract token from Authorization header
+			token, err := extractToken(c)
+			if err != nil {
+				return apperrors.Unauthorized("error.not_authenticated")
+			}
 
-		// Try to get user from cache first
-		user, err := m.getUserFromCache(c.Request.Context(), token)
-		if err == nil && user != nil {
-			// Cache hit - set user in context and continue
+			// Try to get user from cache first
+			user, err := m.getUserFromCache(c.Request().Context(), token)
+			if err == nil && user != nil {
+				// Cache hit - set user in context and continue
+				c.Set(AuthUserKey, user)
+				c.Set(AuthTokenKey, token)
+				return next(c)
+			}
+
+			// Cache miss - look up token in database
+			user, err = m.getUserFromDatabase(token)
+			if err != nil {
+				log.Debug().Err(err).Str("token", token[:8]+"...").Msg("Token authentication failed")
+				return apperrors.Unauthorized("error.invalid_token")
+			}
+
+			// Cache the user ID for future requests
+			if cacheErr := m.cacheUserID(c.Request().Context(), token, user.ID); cacheErr != nil {
+				log.Warn().Err(cacheErr).Msg("Failed to cache user ID")
+			}
+
+			// Set user in context
 			c.Set(AuthUserKey, user)
 			c.Set(AuthTokenKey, token)
-			c.Next()
-			return
+			return next(c)
 		}
-
-		// Cache miss - look up token in database
-		user, err = m.getUserFromDatabase(token)
-		if err != nil {
-			log.Debug().Err(err).Str("token", token[:8]+"...").Msg("Token authentication failed")
-			c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{
-				"error": "Invalid token",
-			})
-			return
-		}
-
-		// Cache the user ID for future requests
-		if cacheErr := m.cacheUserID(c.Request.Context(), token, user.ID); cacheErr != nil {
-			log.Warn().Err(cacheErr).Msg("Failed to cache user ID")
-		}
-
-		// Set user in context
-		c.Set(AuthUserKey, user)
-		c.Set(AuthTokenKey, token)
-		c.Next()
 	}
 }
 
 // OptionalTokenAuth returns middleware that authenticates if token is present but doesn't require it
-func (m *AuthMiddleware) OptionalTokenAuth() gin.HandlerFunc {
-	return func(c *gin.Context) {
-		token, err := extractToken(c)
-		if err != nil {
-			// No token or invalid format - continue without user
-			c.Next()
-			return
-		}
+func (m *AuthMiddleware) OptionalTokenAuth() echo.MiddlewareFunc {
+	return func(next echo.HandlerFunc) echo.HandlerFunc {
+		return func(c echo.Context) error {
+			token, err := extractToken(c)
+			if err != nil {
+				// No token or invalid format - continue without user
+				return next(c)
+			}
 
-		// Try cache first
-		user, err := m.getUserFromCache(c.Request.Context(), token)
-		if err == nil && user != nil {
-			c.Set(AuthUserKey, user)
-			c.Set(AuthTokenKey, token)
-			c.Next()
-			return
-		}
+			// Try cache first
+			user, err := m.getUserFromCache(c.Request().Context(), token)
+			if err == nil && user != nil {
+				c.Set(AuthUserKey, user)
+				c.Set(AuthTokenKey, token)
+				return next(c)
+			}
 
-		// Try database
-		user, err = m.getUserFromDatabase(token)
-		if err == nil {
-			m.cacheUserID(c.Request.Context(), token, user.ID)
-			c.Set(AuthUserKey, user)
-			c.Set(AuthTokenKey, token)
-		}
+			// Try database
+			user, err = m.getUserFromDatabase(token)
+			if err == nil {
+				m.cacheUserID(c.Request().Context(), token, user.ID)
+				c.Set(AuthUserKey, user)
+				c.Set(AuthTokenKey, token)
+			}
 
-		c.Next()
+			return next(c)
+		}
 	}
 }
 
 // extractToken extracts the token from the Authorization header
-func extractToken(c *gin.Context) (string, error) {
-	authHeader := c.GetHeader("Authorization")
+func extractToken(c echo.Context) (string, error) {
+	authHeader := c.Request().Header.Get("Authorization")
 	if authHeader == "" {
 		return "", fmt.Errorf("authorization header required")
 	}
@@ -205,32 +200,29 @@ func (m *AuthMiddleware) InvalidateToken(ctx context.Context, token string) erro
 	return m.cache.InvalidateAuthToken(ctx, token)
 }
 
-// GetAuthUser retrieves the authenticated user from the Gin context
-func GetAuthUser(c *gin.Context) *models.User {
-	user, exists := c.Get(AuthUserKey)
-	if !exists {
+// GetAuthUser retrieves the authenticated user from the Echo context
+func GetAuthUser(c echo.Context) *models.User {
+	user := c.Get(AuthUserKey)
+	if user == nil {
 		return nil
 	}
 	return user.(*models.User)
 }
 
-// GetAuthToken retrieves the auth token from the Gin context
-func GetAuthToken(c *gin.Context) string {
-	token, exists := c.Get(AuthTokenKey)
-	if !exists {
+// GetAuthToken retrieves the auth token from the Echo context
+func GetAuthToken(c echo.Context) string {
+	token := c.Get(AuthTokenKey)
+	if token == nil {
 		return ""
 	}
 	return token.(string)
 }
 
-// MustGetAuthUser retrieves the authenticated user or aborts with 401
-func MustGetAuthUser(c *gin.Context) *models.User {
+// MustGetAuthUser retrieves the authenticated user or returns error with 401
+func MustGetAuthUser(c echo.Context) (*models.User, error) {
 	user := GetAuthUser(c)
 	if user == nil {
-		c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{
-			"error": "Authentication required",
-		})
-		return nil
+		return nil, apperrors.Unauthorized("error.not_authenticated")
 	}
-	return user
+	return user, nil
 }

internal/middleware/timezone.go

@@ -3,7 +3,7 @@ package middleware
 import (
 	"time"
 
-	"github.com/gin-gonic/gin"
+	"github.com/labstack/echo/v4"
 )
 
 const (
@@ -22,21 +22,23 @@ const (
 // or a UTC offset (e.g., "-08:00", "+05:30").
 //
 // If no timezone is provided or it's invalid, UTC is used as the default.
-func TimezoneMiddleware() gin.HandlerFunc {
-	return func(c *gin.Context) {
-		tzName := c.GetHeader(TimezoneHeader)
-		loc := parseTimezone(tzName)
+func TimezoneMiddleware() echo.MiddlewareFunc {
+	return func(next echo.HandlerFunc) echo.HandlerFunc {
+		return func(c echo.Context) error {
+			tzName := c.Request().Header.Get(TimezoneHeader)
+			loc := parseTimezone(tzName)
 
-		// Store the location and the current time in that timezone
-		c.Set(TimezoneKey, loc)
+			// Store the location and the current time in that timezone
+			c.Set(TimezoneKey, loc)
 
-		// Calculate "now" in the user's timezone, then get start of day
-		// For date comparisons, we want to compare against the START of the user's current day
-		userNow := time.Now().In(loc)
-		startOfDay := time.Date(userNow.Year(), userNow.Month(), userNow.Day(), 0, 0, 0, 0, loc)
-		c.Set(UserNowKey, startOfDay)
+			// Calculate "now" in the user's timezone, then get start of day
+			// For date comparisons, we want to compare against the START of the user's current day
+			userNow := time.Now().In(loc)
+			startOfDay := time.Date(userNow.Year(), userNow.Month(), userNow.Day(), 0, 0, 0, 0, loc)
+			c.Set(UserNowKey, startOfDay)
 
-		c.Next()
+			return next(c)
+		}
 	}
 }
 
@@ -76,22 +78,22 @@ func parseTimezone(tz string) *time.Location {
 	return time.UTC
 }
 
-// GetUserTimezone retrieves the user's timezone from the Gin context.
+// GetUserTimezone retrieves the user's timezone from the Echo context.
 // Returns UTC if not set.
-func GetUserTimezone(c *gin.Context) *time.Location {
-	loc, exists := c.Get(TimezoneKey)
-	if !exists {
+func GetUserTimezone(c echo.Context) *time.Location {
+	loc := c.Get(TimezoneKey)
+	if loc == nil {
 		return time.UTC
 	}
 	return loc.(*time.Location)
 }
 
-// GetUserNow retrieves the timezone-aware "now" time from the Gin context.
+// GetUserNow retrieves the timezone-aware "now" time from the Echo context.
 // This represents the start of the current day in the user's timezone.
 // Returns time.Now().UTC() if not set.
-func GetUserNow(c *gin.Context) time.Time {
-	now, exists := c.Get(UserNowKey)
-	if !exists {
+func GetUserNow(c echo.Context) time.Time {
+	now := c.Get(UserNowKey)
+	if now == nil {
 		return time.Now().UTC()
 	}
 	return now.(time.Time)