Skip to content
Unreleased: these pages follow the main branch. The latest release is v0.5.
Protect your app in the browser

Protect your app in the browser

Since v0.6.0

A browser runs your pages’ scripts, sends your cookies with every request to your site, and lets other sites’ pages send requests to it too. Four things keep that safe: CSRF protection (other sites’ pages can’t act as your visitors), the CORS settings (which other sites' scripts may read your answers; by default, none), a Content-Security-Policy (scripts injected into a page don’t run), and escaping (what users typed is shown as text, not run). This guide covers what each stack does by default and what you add, for pages in templ with htmx, in React, Vue or Svelte with Inertia, and for a single-page app that calls your API.

Before you start

An app made with anetos new, of any stack. For the checklist before you go live (HTTPS, secrets, the database’s connection), see Secure your app.

Steps

1. Keep other sites’ requests out (CSRF)

A page on another site can send a form to yours, and the browser adds your visitor’s session cookie. web.CSRF stops that: a request that can change something (any method but GET, HEAD, OPTIONS and TRACE) is refused when the browser says it comes from another origin (Sec-Fetch-Site, Origin), and needs the session’s token. Each stack sends the token its own way, and the generated code wires it (in an API project, make:auth adds the SPA’s part):

StackThe pages’ groupHow the token comes back
web (templ, htmx)web.CSRF()Forms have a _token field (view.CSRFField, in the ui form components); htmx sends the X-CSRF-Token header, from hx-headers on the layout’s <body>
react, vue, svelteweb.CSRF(web.WithXSRFCookie())The app sets an XSRF-TOKEN cookie, and Inertia’s client sends it back in the X-XSRF-TOKEN header
apinone: tokensA browser never adds an Authorization header on its own, so another site’s page can’t send a request with your user’s token
api, with your SPAweb.FirstParty(sessions.Middleware, web.CSRF(web.WithXSRFCookie()))Step 2

What you add:

  • Routes of your own go in the group that has web.CSRF, after the session middleware: route.csrf in the security check finds a route that changes data with the session and no CSRF protection. In an API project, that is routes/auth.go’s api group, or its loggedIn group for routes that need a login; make:crud registers its routes in routes/api.go, open to every client and without sessions: move the call to routes/auth.go, as its comment says, for your SPA’s logged-in user to reach them.
  • A script of your own in a templ page sends the X-CSRF-Token header. The layout writes the token only into hx-headers; give your scripts a tag to read it from, such as <meta name="csrf-token" content={ view.CSRFToken(ctx) }> in the layout’s <head>. In a React, Vue or Svelte page, use Inertia’s router or forms, which send it.
  • A webhook (a payment provider posting to you) goes in a group without sessions, so it needs no token: check its signature instead.
  • Another origin of yours that posts to the app (an admin on admin.example.com): web.CSRF(web.WithTrustedOrigins("https://admin.example.com")).

2. Log your SPA in with a cookie, not a token

A single-page app that keeps an API token in JavaScript loses it to any script injected into the page. An SPA on your own site can log in with the session cookie instead, which scripts can’t read: list its origins in HTTP_SPA_ORIGINS.

HTTP_SPA_ORIGINS=https://app.example.com

Its requests then get a session, CSRF protection with the XSRF-TOKEN cookie, and CORS with credentials; make:auth’s API accounts answer its login with the session instead of a token. Other clients (mobile apps, programs, other sites) keep their tokens. List the origins of production in production’s settings: setting.spa-origins warns of an http:// or localhost origin where the app is deployed.

A cookie only reaches the API from the same site: the same host, or another subdomain of one domain. On another subdomain, SESSION_DOMAIN shares the cookies with it, and has a cost: any other subdomain of the domain can then set a session cookie. Where you can, serve the SPA and the API from one origin (the app serving the SPA, or one proxy in front of both). Log in from your SPA with a session cookie has the steps and the code.

3. Allow other sites’ scripts only where you mean to (CORS)

By default the app sends no CORS headers, so a script on another site can send a request but can’t read the answer. Your SPA’s origins are allowed already (step 2). For a public API that other sites’ pages call with tokens, list those sites:

HTTP_CORS_ORIGINS=https://partner.example.com,https://*.example.org

They are allowed without cookies (HTTP_CORS_CREDENTIALS=false, the default), which is what token clients need: the token goes in the Authorization header, which HTTP_CORS_HEADERS allows. Keep it that way: with credentials, a listed site’s scripts read your pages as your logged-in visitors see them. The app refuses to start with HTTP_CORS_ORIGINS="*" and credentials together; * alone is a warning in the security check (setting.cors), and --url with --level=advanced finds a site that echoes any origin back (live.cors). The settings reference lists the HTTP_CORS_* settings.

4. Add a Content-Security-Policy

A Content-Security-Policy tells the browser where scripts may come from, so a <script> injected into a page doesn’t run. Anetos doesn’t set one for your pages (the admin has its own): a policy has to fit your scripts. This one fits the pages that anetos new and the generators write, in every stack:

// illustrative: in main.go, which imports "net/http" for it
const contentSecurityPolicy = "default-src 'self'; script-src 'self'; " +
	"style-src 'self' 'unsafe-inline'; img-src 'self' data:; object-src 'none'; " +
	"base-uri 'none'; form-action 'self'; frame-ancestors 'self'"

// csp sends the policy with every response.
func csp(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		w.Header().Set("Content-Security-Policy", contentSecurityPolicy)
		next.ServeHTTP(w, r)
	})
}

And in setup, right after web.NewServer, before the routes:

// illustrative
if !app.Config().Env.IsDevelopment() {
	srv.Router().UseGlobal(csp)
}

What it allows, stack by stack:

  • Scripts come from the app only: the web stack’s htmx from /assets/, the React, Vue and Svelte stacks’ build from /build/, an SPA the app serves from its own paths. Inertia’s page data is a <script type="application/json"> element, which the browser reads as data and never runs, so the policy doesn’t need to allow it.
  • Inline styles, 'unsafe-inline': htmx adds a <style> element for its indicators, Inertia’s client one for its progress bar, and admin.Banner (the bar on your pages while an admin acts as a user) has a style attribute. Inline scripts stay blocked. An SPA without Inertia or htmx works with style-src 'self'.
  • Images from the app, and data: URLs: the icons Pico’s and Bootstrap’s CSS draw inline, and the SPA’s empty icon.
  • Development gets no policy: there, the scripts come from Vite’s server at another address, React’s refresh needs an inline script, and anetos dev adds an inline script that reloads the page after a change. Tests (APP_ENV=testing), staging and production get it.

Add the hosts of anything else your pages load (script-src 'self' https://cdn.example.com, connect-src 'self' https://api.example.com for requests to another host). Before you ship, run the build with the policy (go tool anetos build, then the binary with APP_ENV=staging) and open the browser’s console: it names each resource the policy blocks. To try a policy on the live site without breaking pages, send it as Content-Security-Policy-Report-Only first: the browser blocks nothing, and writes what it would block in its console (each visitor’s own; a report-to directive and an endpoint of yours collect them).

The admin’s pages send a stricter policy of their own, and the files the storage handler serves that a browser could run (HTML, SVG) get Content-Security-Policy: sandbox and a download: both replace yours. An SPA served by a CDN or another server gets its policy from that server.

5. Show what users typed as text (XSS)

Each stack escapes what it prints, so <script> typed into a form shows as text. Each also has a way to write HTML as it is, for HTML you trust:

StackEscapedWritten as it is
web{ post.Title } (templ)@templ.Raw(html)
react{post.title}dangerouslySetInnerHTML
vue{{ post.title }}v-html
svelte{post.title}{@html html}

Never write a user’s text as it is. To keep some HTML from users (a rich text editor’s), sanitize it on the server, with an allow-list sanitizer, before saving it. The security check’s source.xss finds request data given to templ.Raw, c.HTML or template.HTML in Go code; it doesn’t read the frontend’s code, so review dangerouslySetInnerHTML, v-html and {@html} yourself (in a react, vue or svelte project, the anetos-security skill reminds coding agents of its framework’s).

Links need a check of their own: escaping a URL doesn’t stop a javascript: URL from running when a link to it is clicked. templ replaces such a URL in href and src with a harmless one, unless you pass it through templ.SafeURL; a link built in a JavaScript framework may keep it. In every stack, validate a URL users give with the url rule (validate:"url"), which accepts http and https only, before saving it.

6. Keep the session cookie yours

The session cookie is HttpOnly (scripts can’t read it), Secure outside development and testing, SameSite=Lax (other sites’ forms and requests don’t carry it; following a link to your site does), and, when Secure and without SESSION_DOMAIN, named with the __Host- prefix, so no other site, subdomains included, can set it. Leave these as they are:

  • SESSION_SAME_SITE=strict keeps the cookie off a link from another site too: a visitor who follows a link in an email arrives logged out. none sends it with other sites’ requests: the security check warns of it (setting.session-same-site).
  • SESSION_DOMAIN shares the cookie with every subdomain: set it only for an SPA on another subdomain (step 2).

The XSRF-TOKEN cookie isn’t HttpOnly: the page’s scripts read it, by design. It holds the CSRF token, not a login.

Pages can’t be framed by other sites either: X-Frame-Options: SAMEORIGIN, from web.NewServer, and frame-ancestors 'self' in the policy above.

How it works

What each part of the app sends the browser:

Header or cookieSent byWhen
X-Content-Type-Options, X-Frame-Options: SAMEORIGIN, Referrer-Policy, Cross-Origin-Opener-Policyweb.NewServer (web.SecureHeaders)Every response
Strict-Transport-Securityweb.NewServerIn production
Access-Control-Allow-*web.NewServerWith HTTP_CORS_ORIGINS or HTTP_SPA_ORIGINS, to those origins
The session cookiesession.New’s middlewarePages and first-party SPAs
XSRF-TOKENweb.CSRF(web.WithXSRFCookie())When the request’s cookie doesn’t hold the session’s token: the first page, and after a login
Content-Security-PolicyYour middleware (step 4); the admin’s; the storage handler’s sandboxAs you set it
Cache-Control: no-storeauth.RequireLogged-in pages

web.CSRF checks the origin with Go’s http.CrossOriginProtection, then the token, from the _token field, the X-CSRF-Token header or the X-XSRF-TOKEN header. A request from a first-party SPA passes the origin check (web.IsFirstParty) and still needs the token. A request without Origin or Sec-Fetch-Site (a program’s, not a browser’s) needs the token too.

Testing it

Tests run with APP_ENV=testing, so they get the policy:

// illustrative
app := anetostest.New(t, setup)
app.Get("/").AssertOK().AssertHeader("Content-Security-Policy", contentSecurityPolicy)

The test client sends the session’s token by itself, in the X-CSRF-Token header, which web.CSRF reads first; to check that a route is protected, send another one there, whatever the stack (a forged X-XSRF-TOKEN would be ignored for the client’s own):

// illustrative
app.WithHeader("X-CSRF-Token", "forged").
	PostForm("/posts", url.Values{"title": {"Hello"}}).AssertForbidden()

In the browser, open the console on each kind of page: a policy that blocks something says so there. After a deploy, go tool anetos security:check --url=https://… checks the live site’s headers and cookies (Check the running site).

Common problems

ProblemCauseFix
403 “Cross-origin request rejected.”The request came from a page on another originList your SPA in HTTP_SPA_ORIGINS, or another origin of yours with web.WithTrustedOrigins
401 for an API’s request from another origin, with the session cookieAn API project’s routes take sessions only for HTTP_SPA_ORIGINS: another origin’s request is a guest’s, or a token client’sList the origin, if it’s your SPA’s
403 “The page has expired. Reload it and try again.”No token, or not the session’s: a page opened before a login in another tab, an expired session, a fetch without the headerReload the page; send the X-CSRF-Token (templ pages) or X-XSRF-TOKEN (cookie) header from your scripts
The console says a script, style or image was refusedThe policy doesn’t allow its hostAdd the host to the policy’s directive the console names
The console reports a CORS errorThe page’s origin isn’t listed, or the request sends cookies to an origin listed without credentialsList it in HTTP_CORS_ORIGINS; for your own SPA with cookies, in HTTP_SPA_ORIGINS
The SPA can’t read XSRF-TOKENThe SPA is on another subdomain than the APISESSION_DOMAIN with the shared domain (Log in from your SPA)
A webhook gets 403Its route has sessions and CSRF protectionMove it to a group without them, and check the sender’s signature

Next steps