Improve CORS documentation

* Provide links to further reading
* Provide security warnings
* Document undocumented wildcard feature
* Update to go-1.19 style links

Author: danielbprice

middleware/cors.go

@@ -15,46 +15,85 @@ type (
 		// Skipper defines a function to skip middleware.
 		Skipper Skipper
 
-		// AllowOrigin defines a list of origins that may access the resource.
+		// AllowOrigins determines the value of the Access-Control-Allow-Origin
+		// response header.  This header defines a list of origins that may access the
+		// resource.  The wildcard characters '*' and '?' are supported and are
+		// converted to regex fragments '.*' and '.' accordingly.
+		//
+		// Security: use extreme caution when handling the origin, and carefully
+		// validate any logic. Remember that attackers may register hostile domain names.
+		// See https://blog.portswigger.net/2016/10/exploiting-cors-misconfigurations-for.html
+		//
 		// Optional. Default value []string{"*"}.
+		//
+		// See also: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin
 		AllowOrigins []string `yaml:"allow_origins"`
 
 		// AllowOriginFunc is a custom function to validate the origin. It takes the
 		// origin as an argument and returns true if allowed or false otherwise. If
 		// an error is returned, it is returned by the handler. If this option is
 		// set, AllowOrigins is ignored.
+		//
+		// Security: use extreme caution when handling the origin, and carefully
+		// validate any logic. Remember that attackers may register hostile domain names.
+		// See https://blog.portswigger.net/2016/10/exploiting-cors-misconfigurations-for.html
+		//
 		// Optional.
 		AllowOriginFunc func(origin string) (bool, error) `yaml:"allow_origin_func"`
 
-		// AllowMethods defines a list methods allowed when accessing the resource.
-		// This is used in response to a preflight request.
+		// AllowMethods determines the value of the Access-Control-Allow-Methods
+		// response header.  This header specified the list of methods allowed when
+		// accessing the resource.  This is used in response to a preflight request.
+		//
 		// Optional. Default value DefaultCORSConfig.AllowMethods.
-		// If `allowMethods` is left empty will fill for preflight request `Access-Control-Allow-Methods` header value
+		// If `allowMethods` is left empty, this middleware will fill for preflight
+		// request `Access-Control-Allow-Methods` header value
 		// from `Allow` header that echo.Router set into context.
+		//
+		// See also: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Methods
 		AllowMethods []string `yaml:"allow_methods"`
 
-		// AllowHeaders defines a list of request headers that can be used when
-		// making the actual request. This is in response to a preflight request.
+		// AllowHeaders determines the value of the Access-Control-Allow-Headers
+		// response header.  This header is used in response to a preflight request to
+		// indicate which HTTP headers can be used when making the actual request.
+		//
 		// Optional. Default value []string{}.
+		//
+		// See also: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Headers
 		AllowHeaders []string `yaml:"allow_headers"`
 
-		// AllowCredentials indicates whether or not the response to the request
-		// can be exposed when the credentials flag is true. When used as part of
-		// a response to a preflight request, this indicates whether or not the
-		// actual request can be made using credentials.
-		// Optional. Default value false.
+		// AllowCredentials determines the value of the
+		// Access-Control-Allow-Credentials response header.  This header indicates
+		// whether or not the response to the request can be exposed when the
+		// credentials mode (Request.credentials) is true. When used as part of a
+		// response to a preflight request, this indicates whether or not the actual
+		// request can be made using credentials.  See also
+		// [MDN: Access-Control-Allow-Credentials].
+		//
+		// Optional. Default value false, in which case the header is not set.
+		//
 		// Security: avoid using `AllowCredentials = true` with `AllowOrigins = *`.
-		// See http://blog.portswigger.net/2016/10/exploiting-cors-misconfigurations-for.html
+		// See "Exploiting CORS misconfigurations for Bitcoins and bounties",
+		// https://blog.portswigger.net/2016/10/exploiting-cors-misconfigurations-for.html
+		//
+		// See also: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Credentials
 		AllowCredentials bool `yaml:"allow_credentials"`
 
-		// ExposeHeaders defines a whitelist headers that clients are allowed to
-		// access.
-		// Optional. Default value []string{}.
+		// ExposeHeaders determines the value of Access-Control-Expose-Headers, which
+		// defines a list of headers that clients are allowed to access.
+		//
+		// Optional. Default value []string{}, in which case the header is not set.
+		//
+		// See also: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Expose-Header
 		ExposeHeaders []string `yaml:"expose_headers"`
 
-		// MaxAge indicates how long (in seconds) the results of a preflight request
-		// can be cached.
-		// Optional. Default value 0.
+		// MaxAge determines the value of the Access-Control-Max-Age response header.
+		// This header indicates how long (in seconds) the results of a preflight
+		// request can be cached.
+		//
+		// Optional. Default value 0.  The header is set only if MaxAge > 0.
+		//
+		// See also: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Max-Age
 		MaxAge int `yaml:"max_age"`
 	}
 )
@@ -69,13 +108,22 @@ var (
 )
 
 // CORS returns a Cross-Origin Resource Sharing (CORS) middleware.
-// See: https://developer.mozilla.org/en/docs/Web/HTTP/Access_control_CORS
+// See also [MDN: Cross-Origin Resource Sharing (CORS)].
+//
+// Security: Poorly configured CORS can compromise security because it allows
+// relaxation of the browser's Same-Origin policy.  See [Exploiting CORS
+// misconfigurations for Bitcoins and bounties] and [Portswigger: Cross-origin
+// resource sharing (CORS)] for more details.
+//
+// [MDN: Cross-Origin Resource Sharing (CORS)]: https://developer.mozilla.org/en/docs/Web/HTTP/Access_control_CORS
+// [Exploiting CORS misconfigurations for Bitcoins and bounties]: https://blog.portswigger.net/2016/10/exploiting-cors-misconfigurations-for.html
+// [Portswigger: Cross-origin resource sharing (CORS)]: https://portswigger.net/web-security/cors
 func CORS() echo.MiddlewareFunc {
 	return CORSWithConfig(DefaultCORSConfig)
 }
 
 // CORSWithConfig returns a CORS middleware with config.
-// See: `CORS()`.
+// See: [CORS].
 func CORSWithConfig(config CORSConfig) echo.MiddlewareFunc {
 	// Defaults
 	if config.Skipper == nil {