Cross-site requests

A page on evil.test can make a visitor’s browser send a POST to your site with the cookies of your site: a cross-site request forgery. Bond.csrf(app) stops it with the headers that browsers add to say where a request comes from, so a form needs no token.

Bond.csrf adds a before filter. A request with a method other than GET, HEAD and OPTIONS (so POST, PUT, PATCH and DELETE) is judged by these rules, in order:

  1. Its Origin is one of the allowed_origins you gave: it passes.
  2. It has a Sec-Fetch-Site header, which every current browser sends: same-origin and none (the visitor typed the address, or used a bookmark) pass. same-site (another subdomain of the site) and cross-site are refused.
  3. It has no Sec-Fetch-Site but has an Origin: it passes when the host of the origin, with its port, is the Host of the request. Origin: null is refused.
  4. It has neither: it passes. A browser sends one of them with a request that can carry a cookie, so this is a program such as curl or another server, and a forged form cannot be one.

A request with two Origin headers, or two Sec-Fetch-Site headers, is refused too: a browser sends one of each.

A refused request is a halted 403 with the text cross-origin request refused; the after filters still run for it, as for any halted answer. A GET is never refused, so a GET that changes something is not protected: keep the changes in POST and the other unsafe methods.

The scheme of the origin is not compared, since the server may sit behind a proxy that ends TLS: an http:// Origin for the same host and port passes, even if the app is served over https://. The proxy must pass the Host header on, or rule 3 refuses a browser that sends no Sec-Fetch-Site.

Allowing another site #

allowed_origins lists the sites that may call your app on purpose, for example a front end on another domain. An origin is written as a browser writes it: "https://admin.example.com", with a port when it is not the default, and no path. The comparison ignores case. The program stops at the call when an entry could never be the Origin of a browser: a path, a query, a fragment or a user (/, ?, #, @), no host, a port that is not 1 to 65535, a scheme that is not http or https, or the default port of the scheme (https://example.com:443), which a browser leaves out of the header: write https://example.com.

import HTTP from "std/http"
import Bond from "pkg/bond/bond"
import Testing from "pkg/bond/testing"

def transfer(conn: Bond.Conn) -> Result[Bond.Conn]
  return ok(Bond.text(conn, 200, "transferred"))
end

def try_post(app: Bond.App, origin: String, site: String) -> Int
  headers = [
    HTTP.Header(name: "Host", value: "example.com"),
    HTTP.Header(name: "Origin", value: origin),
    HTTP.Header(name: "Sec-Fetch-Site", value: site),
  ]
  return Testing.request(app, "POST", "/transfer", headers).status
end

def main() -> Void
  app = (
    Bond.app()
    |> Bond.csrf(["https://admin.example.net"])
    |> Bond.post("/transfer", &transfer)
  )
  puts(try_post(app, "https://example.com", "same-origin"))
  puts(try_post(app, "https://evil.test", "cross-site"))
  puts(try_post(app, "https://admin.example.net", "cross-site"))
  puts(Testing.request(app, "POST", "/transfer").status)
end
Output
200
403
200
200

The last line is a request with no Origin and no Sec-Fetch-Site, as curl sends it. In a test, send the headers yourself, as above, to see how a browser is treated.

This check does not replace SameSite=Lax on the session cookie (which Sessions sets by default); use both.