// Protect endpoint: admin only
route.POST("/admin/users", authMiddleware.Admin(), handler)

// Delete project: group admin required
route.DELETE("/:id", 
    authMiddleware.GroupAdmin(
        middleware.FromIDParam(repos.Project.GetGroupIDByProjectID)
    ), 
    handler
)

// Extract group ID from resource ID and verify user is group admin
func (am *AuthMiddleware) GroupAdmin(extractor IDExtractor) gin.HandlerFunc {
    return func(c *gin.Context) {
        userID := c.GetUint("user_id")
        resourceID := extractor(c)
        
        groupID := am.repos.Project.GetGroupIDByProjectID(resourceID)
        isAdmin := am.isGroupAdmin(userID, groupID)
        
        if !isAdmin {
            c.JSON(403, gin.H{"error": "forbidden"})
            c.Abort()
            return
        }
        c.Next()
    }
}

// Update project: manager or admin
route.PUT("/:id", 
    authMiddleware.GroupManager(
        middleware.FromIDParam(repos.Project.GetGroupIDByProjectID)
    ), 
    handler
)

// Create job: any group member
route.POST("/:id/jobs", 
    authMiddleware.GroupMember(
        middleware.FromIDParam(repos.Project.GetGroupIDByProjectID)
    ), 
    handler
)

// Update user: self or admin
route.PUT("/:id", 
    authMiddleware.UserOrAdmin(), 
    handler
)

// Implementation checks: userID == paramID || isAdmin

// Extract ID from path parameter /:id
middleware.FromIDParam(repos.Project.GetGroupIDByProjectID)

// Usage
route.PUT("/:id", 
    authMiddleware.GroupManager(middleware.FromIDParam(...)), 
    handler
)

// Extract project_id from JSON body
middleware.FromProjectIDInPayload(configfile.CreateConfigFileInput{})

// Usage
route.POST("", 
    authMiddleware.GroupManager(
        middleware.FromProjectIDInPayload(configfile.CreateConfigFileInput{})
    ), 
    handler
)

// Create custom extractor for complex scenarios
customExtractor := func(c *gin.Context) uint {
    // Extract from multiple sources (body, params, query)
    userID := c.GetUint("user_id")
    resourceID := getResourceID(c)
    return resourceID
}

route.DELETE("", 
    authMiddleware.GroupManager(customExtractor), 
    handler
)

// Super admin only
route.GET("/admin/dashboard", authMiddleware.Admin(), handler)
route.POST("/admin/config", authMiddleware.Admin(), handler)

// Group admin for specific group
route.DELETE("/projects/:id", 
    authMiddleware.GroupAdmin(
        middleware.FromIDParam(repos.Project.GetGroupIDByProjectID)
    ), 
    handler
)

// Group manager for specific project
route.PUT("/projects/:id", 
    authMiddleware.GroupManager(
        middleware.FromIDParam(repos.Project.GetGroupIDByProjectID)
    ), 
    handler
)

route.POST("/projects/:id/images", 
    authMiddleware.GroupManager(
        middleware.FromIDParam(repos.Project.GetGroupIDByProjectID)
    ), 
    handler
)

// Any group member
route.POST("/projects/:id/jobs", 
    authMiddleware.GroupMember(
        middleware.FromIDParam(repos.Project.GetGroupIDByProjectID)
    ), 
    handler
)

route.GET("/projects/:id/images", 
    authMiddleware.GroupMember(
        middleware.FromIDParam(repos.Project.GetGroupIDByProjectID)
    ), 
    handler
)

// Self or super admin
route.PUT("/users/:id", 
    authMiddleware.UserOrAdmin(), 
    handler
)

route.DELETE("/users/:id", 
    authMiddleware.UserOrAdmin(), 
    handler
)

// internal/api/routes/project.go
func registerProjectRoutes(auth *gin.RouterGroup, handlers *handlers.Handlers, repos *repository.Repos) {
    projects := auth.Group("/projects")
    {
        // List: public to all authenticated users
        projects.GET("", handlers.Project.GetProjects)
        
        // Create: admin only
        projects.POST("", 
            authMiddleware.Admin(), 
            handlers.Project.CreateProject,
        )
        
        // Update: group manager for this project
        projects.PUT("/:id", 
            authMiddleware.GroupManager(
                middleware.FromIDParam(repos.Project.GetGroupIDByProjectID)
            ), 
            handlers.Project.UpdateProject,
        )
        
        // Delete: group admin for this project
        projects.DELETE("/:id", 
            authMiddleware.GroupAdmin(
                middleware.FromIDParam(repos.Project.GetGroupIDByProjectID)
            ), 
            handlers.Project.DeleteProject,
        )
        
        // Nested: config files under project
        projects.POST("/:id/config-files",
            authMiddleware.GroupMember(
                middleware.FromIDParam(repos.Project.GetGroupIDByProjectID)
            ),
            handlers.ConfigFile.CreateConfigFileHandler,
        )
    }
}

// internal/api/middleware/extractors.go
package middleware

import (
    "github.com/gin-gonic/gin"
)

// IDExtractor extracts resource ID from request context
type IDExtractor func(*gin.Context) uint

// FromIDParam extracts ID from URL parameter /:id
func FromIDParam(fetcher func(uint) (uint, error)) IDExtractor {
    return func(c *gin.Context) uint {
        id := c.GetUint("id")  // Gin parses :id from path
        groupID, err := fetcher(id)
        if err != nil {
            c.JSON(404, gin.H{"error": "resource not found"})
            c.Abort()
            return 0
        }
        return groupID
    }
}

// FromProjectIDInPayload extracts project_id from request body
func FromProjectIDInPayload(dto interface{}) IDExtractor {
    return func(c *gin.Context) uint {
        var data map[string]interface{}
        c.BindJSON(&data)
        
        projectID, ok := data["project_id"].(float64)
        if !ok {
            c.JSON(400, gin.H{"error": "project_id required"})
            c.Abort()
            return 0
        }
        
        return uint(projectID)
    }
}

// internal/api/middleware/auth.go
func (am *AuthMiddleware) GroupManager(extractor IDExtractor) gin.HandlerFunc {
    return func(c *gin.Context) {
        userID := c.GetUint("user_id")
        claims := c.MustGet("claims").(*jwt.Claims)
        
        // Super admin bypasses all checks
        if claims.IsAdmin {
            c.Next()
            return
        }
        
        // Extract resource group
        groupID := extractor(c)
        
        // Check if user is group manager or admin
        userGroup, err := am.repos.UserGroup.GetUserGroup(
            c.Request.Context(), 
            userID, 
            groupID,
        )
        
        if err != nil || userGroup == nil || userGroup.Role != "manager" {
            c.JSON(403, gin.H{
                "error": "forbidden",
                "required": "group_manager",
            })
            c.Abort()
            return
        }
        
        c.Next()
    }
}

Request → Check JWT Token
    ↓
    ├─ No Token? → 401 Unauthorized
    │
    ├─ Token Valid?
    │   ├─ No → 401 Unauthorized
    │   ├─ Yes → Extract Claims (userID, isAdmin)
    │
    ├─ Is Super Admin (isAdmin == true)?
    │   ├─ Yes → Allow (skip resource checks)
    │   ├─ No → Continue to resource level
    │
    ├─ Required Role Level?
    │   ├─ Admin → 403 Forbidden
    │   ├─ GroupAdmin → Check group membership + role
    │   ├─ GroupManager → Check group membership + role
    │   ├─ GroupMember → Check group membership
    │   ├─ UserOrAdmin → Check userID == paramID
    │
    ├─ Authorization Check Result?
    │   ├─ Allowed → Call Handler
    │   ├─ Denied → Log, Return 403 Forbidden

Question: What's the minimum role to access this endpoint?

├─ Super Admin Functions? → authMiddleware.Admin()
├─ Group-Level Operation? → authMiddleware.GroupAdmin()
├─ Project Management? → authMiddleware.GroupManager()
├─ User Participation? → authMiddleware.GroupMember()
└─ Self-Service? → authMiddleware.UserOrAdmin()

// Before
route.PUT("/:id", handler)

// After
route.PUT("/:id", 
    authMiddleware.GroupManager(
        middleware.FromIDParam(repos.Project.GetGroupIDByProjectID)
    ),
    handler,
)

func (h *Handler) UpdateProject(c *gin.Context) {
    // If we reach here, authorization already passed
    userID := c.GetUint("user_id")  // Guaranteed valid
    projectID := c.GetUint("id")     // Guaranteed valid
    
    // Continue with business logic
}

// Test: User without permission
func TestUpdateProjectUnauthorized(t *testing.T) {
    // Create project in group A
    // Login as member of group B
    // PUT /projects/{groupA_projectID}
    // Expect: 403 Forbidden
}

// Test: User with permission
func TestUpdateProjectAuthorized(t *testing.T) {
    // Create project in group A
    // Login as manager of group A
    // PUT /projects/{projectID}
    // Expect: 200 OK or 204 No Content
}

// WRONG: Only checks if user exists
route.PUT("/:id", middleware.JWTAuthMiddleware(), handler)

// CORRECT: Verifies user can access this specific resource
route.PUT("/:id", 
    authMiddleware.GroupManager(
        middleware.FromIDParam(repos.Project.GetGroupIDByProjectID)
    ), 
    handler
)

// WRONG: User can modify their own request
projectID := c.Query("project_id")  // User can change this!

// CORRECT: Extract from URL path or verified source
projectID := c.GetUint("id")  // From router
groupID := repos.Project.GetGroupIDByProjectID(projectID)  // Verified

// WRONG: Admin can't access when checking strict membership
isManager := userGroup.Role == "manager"

// CORRECT: Admin bypasses all checks
if claims.IsAdmin || userGroup.Role == "manager" {
    c.Next()
}

// WRONG: Leaks whether resource exists
if user.ID != userID {
    return 404  // Resource doesn't exist?
}

// CORRECT: Same error for missing vs. unauthorized
if user.ID != userID {
    return 403  // Forbidden (could mean not yours)
}

// WRONG: Silent authorization failure
if !authorized {
    c.Abort()
}

// CORRECT: Log all decisions
logger.Warn("authorization failed",
    "user_id", userID,
    "resource", resourceID,
    "action", c.Request.Method,
    "required_role", "manager",
)
if !authorized {
    c.Abort()
}

internal/
├── api/
│   ├── middleware/
│   │   ├── jwt.go              # JWT validation, claims extraction
│   │   ├── auth.go             # AuthMiddleware implementation
│   │   └── extractors.go       # IDExtractor implementations
│   └── routes/
│       ├── router.go           # Main router setup
│       ├── audit.go            # Audit routes
│       ├── auth.go             # Auth routes (public)
│       ├── project.go          # Project routes with authorization
│       └── ...                 # Feature-specific routes
└── domain/
    └── user/
        └── role.go             # Role definitions, constants