docs(auth): fix misleading withSecurityHeaders CONSUMER NOTE

Per Copilot review on PR #290 (post-merge), the previous note suggested custom
HTML handlers could fix CSP blocking by "moving scripts/styles to external files
served from 'self'". That's wrong: the wrapper applies default-src 'none', so
even self-hosted scripts/styles/forms are blocked, and sandbox additionally
disables script execution and form submission outright.

The only viable path for an HTML custom handler is option (a): override the CSP
on its own response. The note now spells out what the wrapper actually does and
gives a concrete example of a relaxed CSP for a form-based custom provider.

Docstring-only change in both v1 (auth.go) and v2 (v2/auth.go). No behavior change.

Author: paskal

auth.go

@@ -258,11 +258,14 @@ func (s *Service) Handlers() (authHandler, avatarHandler http.Handler) {
 //
 // CONSUMER NOTE: custom providers added via Service.AddCustomHandler / AddProvider
 // are also wrapped. If a custom provider renders HTML (login forms, JS-based flows,
-// the dev_provider's login page, etc.), the strict CSP will block inline scripts and
-// event handlers on those pages. Such providers should either (a) override the CSP
-// for their own response by calling w.Header().Set("Content-Security-Policy", ...)
-// before writing — Set replaces the wrapper's value — or (b) move any required
-// scripts/styles to external files served from 'self'.
+// the dev_provider's login page, etc.), this CSP will block everything on the page:
+// default-src 'none' rules out scripts, styles, fonts, images and form targets even
+// when served from 'self', and the sandbox directive disables form submission and
+// script execution outright. Such providers must override the CSP for their own
+// response by calling w.Header().Set("Content-Security-Policy", ...) before writing
+// — Set replaces the wrapper's value — relaxing only the directives the page
+// actually needs (for example script-src 'self'; style-src 'self'; form-action 'self';
+// sandbox allow-forms allow-scripts).
 func withSecurityHeaders(next http.Handler) http.Handler {
 	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		w.Header().Set("Content-Security-Policy", "default-src 'none'; sandbox; frame-ancestors 'none'")

v2/auth.go

@@ -259,11 +259,14 @@ func (s *Service) Handlers() (authHandler, avatarHandler http.Handler) {
 //
 // CONSUMER NOTE: custom providers added via Service.AddCustomHandler / AddProvider
 // are also wrapped. If a custom provider renders HTML (login forms, JS-based flows,
-// the dev_provider's login page, etc.), the strict CSP will block inline scripts and
-// event handlers on those pages. Such providers should either (a) override the CSP
-// for their own response by calling w.Header().Set("Content-Security-Policy", ...)
-// before writing — Set replaces the wrapper's value — or (b) move any required
-// scripts/styles to external files served from 'self'.
+// the dev_provider's login page, etc.), this CSP will block everything on the page:
+// default-src 'none' rules out scripts, styles, fonts, images and form targets even
+// when served from 'self', and the sandbox directive disables form submission and
+// script execution outright. Such providers must override the CSP for their own
+// response by calling w.Header().Set("Content-Security-Policy", ...) before writing
+// — Set replaces the wrapper's value — relaxing only the directives the page
+// actually needs (for example script-src 'self'; style-src 'self'; form-action 'self';
+// sandbox allow-forms allow-scripts).
 func withSecurityHeaders(next http.Handler) http.Handler {
 	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		w.Header().Set("Content-Security-Policy", "default-src 'none'; sandbox; frame-ancestors 'none'")