nosurf Go Middleware

nosurf uses a multi-layered approach to verify that non-safe HTTP requests are coming from a trusted origin. This is critical for preventing CSRF attacks.

1. Sec-Fetch-Site header: If a modern browser sends this header with the value same-origin, nosurf allows the request (subject to CSRF token verification).
2. Origin or Referer headers: If Sec-Fetch-Site is missing or not same-origin, nosurf compares the request's Origin (or Referer if Origin is missing) against the website's own origin.

Note on Origin Construction: Because TLS is often terminated at a load balancer, nosurf cannot always know if the site is running over HTTPS. By default, it assumes HTTPS. If your site uses HTTP, you must configure this manually using SetIsTLSFunc to avoid breakage.

nosurf is an HTTP middleware package for Go that prevents Cross-Site Request Forgery (CSRF) attacks. It provides a CSRFHandler that wraps your existing http.Handler. The middleware automatically checks for CSRF attacks on every non-safe HTTP method (any method that is not GET, HEAD, OPTIONS, or TRACE).

http.ListenAndServe(":8000", nosurf.New(myHandler))

When an endpoint is exempted from automatic checks (e.g., for JSON payloads), you must manually verify the token. Use nosurf.Token(r) to get the token from the cookie and compare it against the token provided in the request body using nosurf.VerifyToken(tkn, tkn2 string) bool.

func HandleJson(w http.ResponseWriter, r *http.Request) {
	d := struct{
		X,Y int
		Tkn string
	}{}
	json.Unmarshal(ioutil.ReadAll(r.Body), &d)
	if !nosurf.VerifyToken(nosurf.Token(r), d.Tkn) {
		http.Errorf(w, "CSRF token incorrect", http.StatusBadRequest)
		return
	}
	// do smth cool
}

Versions prior to 1.2.0 did not correctly apply trusted origin checks for non-safe HTTP requests, leading to CVE-2025-46721.

Post-upgrade requirements:

• Standard HTTPS sites (no cross-origin requests): No code changes are typically required as Sec-Fetch-Site or the default HTTPS origin check will suffice.
• Plaintext HTTP sites: You must call SetIsTLSFunc() to correctly identify secure vs insecure requests.
• Sites requiring cross-origin requests: You must call SetIsAllowedOriginFunc() to validate and permit those specific origins.

nosurf uses two types of tokens to prevent CSRF attacks while maintaining security:

1. Real Token: A 32-byte random value. This is the 'reference' value stored in a base64-encoded cookie. It is used as the source of truth for comparison.
2. Masked Token: A 64-byte value used in forms or headers. It consists of a 32-byte key used for one-time pad masking, followed by the 32-byte 'real' token masked by that key. This ensures that the token value sent to the client changes with every request, preventing certain types of token leakage attacks.

When using VerifyToken, the function automatically detects if the input strings are masked or unmasked based on their decoded length.

To protect your application from CSRF attacks, wrap your main http.Handler with nosurf.

Use nosurf.New(handler) if you need access to the CSRFHandler struct to configure options like custom cookies or failure handlers. Use nosurf.NewPure(handler) if you only need the middleware as a standard http.Handler and don't require further configuration.

You can exempt specific URLs from CSRF checks using exact paths, glob patterns, regular expressions, or a custom function.

Important Note on Paths: Go's paths include a leading slash (e.g., /api/v1/login). Ensure your exemption strings include this leading slash.

Exemption Priority: When IsExempt is called, it checks exemptions in this order:

1. The custom ExemptFunc (if provided).
2. Exact path matches.
3. Glob pattern matches.
4. Regular expression matches.

If your application expects and requires cross-origin requests (e.g., requests from a different domain), you must explicitly permit them.

Use the SetIsAllowedOriginFunc method on your nosurf.CSRFHandler. You must provide a delegate function that validates whether the incoming origin is allowed to issue non-safe requests to your website. If this function returns false, nosurf will abort the request.

Use nosurf.Token(r) to retrieve the current CSRF token from the request. This token is typically used to populate a hidden input field in an HTML form to ensure subsequent POST requests are authenticated.

context["token"] = nosurf.Token(r)

If your website is served via plaintext HTTP (or a mix of HTTP and HTTPS), you must tell nosurf how to determine if an individual request is secure. This is necessary because nosurf needs to know the correct scheme (http vs https) to construct the 'self' origin for comparison.

Use the SetIsTLSFunc method on your nosurf.CSRFHandler and provide a function that takes an http.Request and returns a bool indicating if the request is secure.

If you need to handle CSRF tokens manually (e.g., via JSON bodies), you must first exempt the specific endpoint from automatic verification using the CSRFHandler methods. Available exemption methods include:

• ExemptFunc(fn func(r *http.Request) bool): Uses a custom function to determine exemption.
• ExemptGlob(pattern string): Uses a glob pattern.
• ExemptGlobs(patterns ...string): Uses multiple glob patterns.
• ExemptPath(path string): Uses an exact URL path.
• ExemptPaths(paths ...string): Uses multiple exact URL paths.
• ExemptRegexp(re interface{}): Uses a regular expression.
• ExemptRegexps(res ...interface{}): Uses multiple regular expressions.