Rework origin checks (#74)

Addresses CVE-2025-46721.

Author: justinas

docs/origin-checks.md

@@ -0,0 +1,83 @@
+# Trusted origin checks in nosurf
+
+Before version 1.2.0, nosurf did not correctly apply trusted origin checks for non-safe HTTP requests.
+This resulted in [CVE-2025-46721](https://www.cve.org/CVERecord?id=CVE-2025-46721).
+
+To alleviate this, existing checks for the `Referer` header were fixed,
+and additional methods of checking the origin of requests were added.
+
+As this was technically a breaking change in nosurf, this document attempts to shed light on how origin checks function in nosurf,
+and how users can avoid potential breakage.
+
+
+<!-- vim-markdown-toc GFM -->
+
+* [How does nosurf check the origin?](#how-does-nosurf-check-the-origin)
+    * [1. `Sec-Fetch-Site` header](#1-sec-fetch-site-header)
+    * [2. `Origin` or `Referer` headers](#2-origin-or-referer-headers)
+* [What do I need to do after upgrading to 1.2.0?](#what-do-i-need-to-do-after-upgrading-to-120)
+* [What are the risks of not upgrading to 1.2.0?](#what-are-the-risks-of-not-upgrading-to-120)
+
+<!-- vim-markdown-toc -->
+
+## How does nosurf check the origin?
+
+### 1. `Sec-Fetch-Site` header
+
+[`Sec-Fetch-Site`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Sec-Fetch-Site) is a request header
+sent by [all modern browsers](https://caniuse.com/mdn-http_headers_sec-fetch-site).
+If the incoming request contains a `Sec-Fetch-Site` header with the value `same-origin`,
+nosurf lets the request through (subject to further verification of the CSRF token).
+
+### 2. `Origin` or `Referer` headers
+
+If the `Sec-Fetch-Site` header is not present on the incoming request, or has a value other than `same-origin`,
+nosurf must directly compare the website's origin against the origin the request was made from.
+
+Web content's [origin](https://developer.mozilla.org/en-US/docs/Glossary/Origin) consists of
+a *scheme* (usually `http` or `https`), followed by the host (e.g. `example.com`), optionally followed by a port
+(if a non-standard HTTP/HTTPS port is used).
+This raises a problem for nosurf: because TLS may be terminated before it reaches the Go application
+(e.g. by a load balancer or a reverse proxy),
+in the general case nosurf can not tell whether the website is being served over HTTPS.
+However, that information is mandatory in order to know the full "self" origin of the website.
+
+By default, nosurf will assume that the website is using HTTPS.
+This avoids breakage in most production scenarios, but (in conjunction with `Sec-Fetch-Site` not being present),
+can cause errors in local development scenarios.
+To this end, nosurf provides a [`SetIsTLSFunc`](https://pkg.go.dev/github.com/justinas/nosurf#CSRFHandler.SetIsTLSFunc) method.
+This method requires a user-supplied delegate function, a boolean value indicating whether an incoming request is considered secure.
+
+After constructing a full "self" origin from this boolean indicator and the information found in the `Host` header,
+nosurf will compare the value of the `Origin` header on the incoming request against the self-origin.
+If the origins are equal, request will proceed with further CSRF token checks.
+If the origins aren't equal, nosurf will invoke the user-supplied delegate (if any) set by calling 
+[`SetIsAllowedOriginFunc`](https://pkg.go.dev/github.com/justinas/nosurf#CSRFHandler.SetIsAllowedOriginFunc).
+If the delegate returns `false`, the request will be considered cross-origin and get aborted.
+
+In the unlikely case where `Origin` header does not exist,
+nosurf will perform the same validations documented above on the `Referer` header.
+
+In the very unlikely case that no `Referer` header is present either, the request will be aborted.
+
+## What do I need to do after upgrading to 1.2.0?
+
+* If your website does not utilize mutating cross-origin requests, and you have no visitors using grossly outdated browsers,
+  the check for `Sec-Fetch-Site` will be sufficient, and you do not need to make any changes to your code.
+* If you expect your site to be visited by user with outdated browsers that do not implement the `Sec-Fetch-Site` header,
+  but the site is served via HTTPS and you do not expect cross-origin requests, you do not need to make any changes to your code.
+* If you are serving via plaintext HTTP (some or all of the time), when configuring nosurf, you must call `SetIsTLSFunc()`,
+  passing it a function that correctly determines this per individual request.
+* If you expect cross-origin requests, you must call `SetIsAllowedOriginFunc()`,
+  passing it a function that validates whether the origin is allowed to issue non-safe requests to your website.
+
+## What are the risks of not upgrading to 1.2.0?
+
+You may be susceptible to cross-site request forgery due to [CVE-2025-46721](https://www.cve.org/CVERecord?id=CVE-2025-46721).
+
+However, as nosurf's CSRF token validation logic is thought to be sound,
+all known exploits require the attacker to have control over the HTML content of a page on your website,
+or on a page hosted on a subdomain under your website's domain (e.g. `attacker.example.com` if your website is `example.com`)
+in order to extract or override the CSRF token set in the cookie by nosurf.
+
+Despite the minimal risk, I recommend that you upgrade nosurf to the latest version.

handler.go

@@ -28,10 +28,14 @@ var safeMethods = []string{"GET", "HEAD", "OPTIONS", "TRACE"}
 // reasons for CSRF check failures
 var (
 	ErrNoReferer  = errors.New("A secure request contained no Referer or its value was malformed")
-	ErrBadReferer = errors.New("A secure request's Referer comes from a different Origin" +
+	ErrBadReferer = errors.New("A secure request's Referer comes from a different origin" +
 		" from the request's URL")
-	ErrBadToken = errors.New("The CSRF token in the cookie doesn't match the one" +
+	ErrBadOrigin = errors.New("Request was made with a disallowed origin specified in the Origin header")
+	ErrBadToken  = errors.New("The CSRF token in the cookie doesn't match the one" +
 		" received in a form/header.")
+
+	// Internal error. When this is raised, and the request is secure, we additionally check for Referer.
+	errNoOrigin = errors.New("Origin header was not present")
 )
 
 type CSRFHandler struct {
@@ -45,7 +49,9 @@ type CSRFHandler struct {
 	baseCookie http.Cookie
 
 	// Slices of paths that are exempt from CSRF checks.
-	// They can be specified by...
+	// All of those will be matched against Request.URL.Path,
+	// So they should take the leading slash into account
+	// Paths can be specified by...
 	// ...an exact path,
 	exemptPaths []string
 	// ...a regexp,
@@ -55,8 +61,8 @@ type CSRFHandler struct {
 	// ...or a custom matcher function
 	exemptFunc func(r *http.Request) bool
 
-	// All of those will be matched against Request.URL.Path,
-	// So they should take the leading slash into account
+	isTLS           func(r *http.Request) bool
+	isAllowedOrigin func(r *url.URL) bool
 }
 
 func defaultFailureHandler(w http.ResponseWriter, r *http.Request) {
@@ -95,6 +101,7 @@ func New(handler http.Handler) *CSRFHandler {
 	csrf := &CSRFHandler{successHandler: handler,
 		failureHandler: http.HandlerFunc(defaultFailureHandler),
 		baseCookie:     baseCookie,
+		isTLS:          func(r *http.Request) bool { return true },
 	}
 
 	return csrf
@@ -145,26 +152,10 @@ func (h *CSRFHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	// if the request is secure, we enforce origin check
-	// for referer to prevent MITM of http->https requests
-	if r.URL.Scheme == "https" {
-		referer, err := url.Parse(r.Header.Get("Referer"))
-
-		// if we can't parse the referer or it's empty,
-		// we assume it's not specified
-		if err != nil || referer.String() == "" {
-			ctxSetReason(r, ErrNoReferer)
-			h.handleFailure(w, r)
-			return
-		}
-
-		// if the referer doesn't share origin with the request URL,
-		// we have another error for that
-		if !sameOrigin(referer, r.URL) {
-			ctxSetReason(r, ErrBadReferer)
-			h.handleFailure(w, r)
-			return
-		}
+	if err := h.ensureSameOrigin(r); err != nil {
+		ctxSetReason(r, err)
+		h.handleFailure(w, r)
+		return
 	}
 
 	// Finally, we check the token itself.
@@ -193,6 +184,75 @@ func (h *CSRFHandler) handleFailure(w http.ResponseWriter, r *http.Request) {
 	h.failureHandler.ServeHTTP(w, r)
 }
 
+func (h *CSRFHandler) ensureSameOrigin(r *http.Request) error {
+	selfOrigin := &url.URL{
+		Scheme: "http",
+		Host:   r.Host,
+	}
+	isTLS := h.isTLS(r)
+	if isTLS {
+		selfOrigin.Scheme = "https"
+	}
+
+	secFetchSite := r.Header.Get("Sec-Fetch-Site")
+	if secFetchSite == "same-origin" {
+		return nil
+	}
+
+	// If no `Sec-Fetch-Site: same-origin` is present, fallback to Origin or Referer,
+	// including considering custom allowed origins.
+	err := h.checkOrigin(selfOrigin, r)
+	if err == nil {
+		return nil
+	} else if !errors.Is(err, errNoOrigin) {
+		return err
+	}
+
+	// If Origin header was not present, fall back on Referer check for both secure and insecure requests.
+	// This is opposite of Django's behavior, but should be fine, as neither of the three headers existing is an edge case.
+	// https://github.com/django/django/blob/8be0c0d6901669661fca578f474cd51cd284d35a/django/middleware/csrf.py#L460
+	return h.checkReferer(selfOrigin, r)
+}
+
+func (h *CSRFHandler) checkReferer(selfOrigin *url.URL, r *http.Request) error {
+	referer, err := url.Parse(r.Referer())
+	if err != nil || referer.String() == "" {
+		return ErrNoReferer
+	}
+
+	if sameOrigin(selfOrigin, referer) {
+		return nil
+	}
+
+	if h.isAllowedOrigin != nil && h.isAllowedOrigin(referer) {
+		return nil
+	}
+
+	return ErrBadReferer
+}
+
+func (h *CSRFHandler) checkOrigin(selfOrigin *url.URL, r *http.Request) error {
+	originStr := r.Header.Get("Origin")
+	if originStr == "" || originStr == "null" {
+		return errNoOrigin
+	}
+
+	origin, err := url.Parse(originStr)
+	if err != nil {
+		return err
+	}
+
+	if sameOrigin(selfOrigin, origin) {
+		return nil
+	}
+
+	if h.isAllowedOrigin != nil && h.isAllowedOrigin(origin) {
+		return nil
+	}
+
+	return ErrBadOrigin
+}
+
 // Generates a new token, sets it on the given request and returns it
 func (h *CSRFHandler) RegenerateToken(w http.ResponseWriter, r *http.Request) string {
 	token := generateToken()
@@ -224,3 +284,73 @@ func (h *CSRFHandler) SetFailureHandler(handler http.Handler) {
 func (h *CSRFHandler) SetBaseCookie(cookie http.Cookie) {
 	h.baseCookie = cookie
 }
+
+// SetIsTLSFunc sets a delegate function which determines, on a per-request basis, whether the request is made over a secure connection.
+// This should return `true` iff the URL that the user uses to access the application begins with https://.
+// For example, if the Go web application is served via plain-text HTTP,
+// but the user is accessing it through HTTPS via a TLS-terminating reverse-proxy, this should return `true`.
+//
+// Examples:
+//
+// 1. If you're using the Go TLS stack (no TLS-terminating proxies in between the user and the app), you may use:
+//
+//	h.SetIsTLSFunc(func(r *http.Request) bool { return r.TLS != nil })
+//
+// 2. If your application is behind a reverse proxy that terminates TLS, you should configure the reverse proxy
+// to report the protocol that the request was made over via an HTTP header,
+// e.g. `X-Forwarded-Proto`.
+// You should also validate that the request is coming in from an IP of a trusted reverse proxy
+// to ensure that this header has not been spoofed by an attacker. For example:
+//
+//	var trustedProxies = []string{"198.51.100.1", "198.51.100.2"}
+//	h.SetIsTLSFunc(func(r *http.Request) bool {
+//		ip, _, _ := strings.Cut(r.RemoteAddr, ":")
+//		proto := r.Header.Get("X-Forwarded-Proto")
+//		return slices.Contains(trustedProxies, ip) && proto == "https"
+//	})
+func (h *CSRFHandler) SetIsTLSFunc(f func(*http.Request) bool) {
+	h.isTLS = f
+}
+
+// SetAllowedOrigins defines a function that checks whether the request comes from an allowed origin.
+// This function will be invoked when the request is not considered a same-origin request.
+// If this function returns `false`, request will be disallowed.
+//
+// In most cases, this will be used with [StaticOrigins].
+func (h *CSRFHandler) SetIsAllowedOriginFunc(f func(*url.URL) bool) {
+	h.isAllowedOrigin = f
+}
+
+// StaticOrigins returns a delegate, suitable for passing to [CSRFHandler.SetIsAllowedOriginFunc],
+// that validates the request origin against a static list of allowed origins.
+// This function expects each element to be of form `scheme://host`, e.g.: `https://example.com`, `http://example.org`.
+// If any element of the slice is an invalid URL, this function will return an error.
+// If an element includes additional URL parts (e.g. a path), these parts will be ignored,
+// as origin checks only take the scheme and host into account.
+//
+// Example:
+//
+//	h := nosurf.New()
+//	origins, err := nosurf.StaticOrigins("https://api.example.com", "http://insecure.example.com")
+//	if err != nil {
+//		panic(err)
+//	}
+//	h.SetIsAllowedOriginFunc(origins)
+func StaticOrigins(origins ...string) (func(r *url.URL) bool, error) {
+	var allowedOrigins []*url.URL
+	for _, o := range origins {
+		url, err := url.Parse(o)
+		if err != nil {
+			return nil, err
+		}
+		allowedOrigins = append(allowedOrigins, url)
+	}
+	return func(u *url.URL) bool {
+		for _, candidate := range allowedOrigins {
+			if sameOrigin(candidate, u) {
+				return true
+			}
+		}
+		return false
+	}, nil
+}