package middleware

import (
	"github.com/labstack/echo/v4"
	"github.com/labstack/echo/v4/middleware"
)

// NewCORSMiddleware creates and configures Cross-Origin Resource Sharing (CORS) middleware
// for the Echo web framework. CORS is a security feature that controls which origins
// (domains) are allowed to make requests to your API from web browsers.
//
// Security Context:
// Browsers enforce the Same-Origin Policy, which prevents JavaScript on one domain
// from accessing resources on another domain. CORS relaxes this restriction by
// allowing servers to explicitly specify which origins are trusted.
//
// Configuration Details:
//
//   - AllowOrigins: Whitelist of trusted frontend origins that can access the API.
//     Currently configured for local development (React dev server on 5173, alternative on 3000).
//     Production deployment should update this to include actual frontend domain(s).
//
//   - AllowMethods: HTTP methods permitted for cross-origin requests.
//     Includes standard REST operations plus OPTIONS for preflight requests.
//
//   - AllowHeaders: Request headers that browsers are allowed to send.
//     Authorization header is critical for JWT bearer tokens.
//
//   - AllowCredentials: Allows browsers to send credentials (cookies, authorization headers)
//     with cross-origin requests. Required for JWT authentication.
//     IMPORTANT: When true, AllowOrigins cannot use wildcards (*) for security.
//
//   - MaxAge: Duration (in seconds) that browsers can cache preflight OPTIONS responses.
//     3600 seconds (1 hour) reduces preflight requests for better performance.
//
// Preflight Requests:
// For certain cross-origin requests (e.g., those with Authorization headers or
// non-simple methods like PUT/DELETE), browsers automatically send an OPTIONS
// request first to check if the actual request is allowed. This middleware
// handles those preflight requests automatically.
//
// Usage:
//
//	e := echo.New()
//	e.Use(NewCORSMiddleware())
//
// Production Considerations:
//   - Update AllowOrigins to include production frontend domain(s)
//   - Remove localhost origins in production builds
//   - Consider environment-based configuration for different deployment stages
//   - Never use "*" with AllowCredentials: true (security vulnerability)
//
// Returns:
//
//	Echo middleware function that handles CORS for all routes
func NewCORSMiddleware() echo.MiddlewareFunc {
	return middleware.CORSWithConfig(middleware.CORSConfig{
		// AllowOrigins specifies which frontend domains can make requests to this API.
		// These are the URLs where your React/Vue/Angular frontend is hosted.
		// Browser will reject requests from any origin not in this list.
		// TODO: Update this list for production deployment (e.g., "https://app.aurganize.com")
		AllowOrigins: []string{"http://localhost:5173", "http://localhost:3000"},

		// AllowMethods defines which HTTP methods are permitted for cross-origin requests.
		// OPTIONS is required for handling CORS preflight requests.
		// GET, POST, PUT, DELETE, PATCH cover standard REST API operations.
		AllowMethods: []string{"GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"},

		// AllowHeaders specifies which request headers browsers can send in cross-origin requests.
		// - Origin: Browser automatically sends this, required for CORS
		// - Content-Type: Needed for sending JSON request bodies
		// - Accept: Specifies expected response format
		// - Authorization: Critical for JWT bearer token authentication
		AllowHeaders: []string{"Origin", "Content-Type", "Accept", "Authorization"},

		// AllowCredentials permits browsers to send credentials (cookies, HTTP auth, TLS certificates)
		// with cross-origin requests. Must be true for JWT authentication in Authorization header.
		// Security note: When true, AllowOrigins MUST NOT use wildcard "*"
		AllowCredentials: true,

		// MaxAge specifies how long (in seconds) browsers can cache the preflight response.
		// During this time, browsers won't send additional OPTIONS requests for the same endpoint.
		// 3600 seconds = 1 hour, balancing performance with configuration change responsiveness.
		MaxAge: 3600,
	})
}