CSRF Protection

The tag places the token. The handler has to call request.form("name") to check it.

<form method="post" action="/submit">
    {% csrf %}
    <input type="text" name="data">
    <button type="submit">Send</button>
</form>

const csrfToken = document.querySelector('[name="csrf_token"]').value;

fetch('/api/endpoint', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'X-CSRF-Token': csrfToken
    },
    body: JSON.stringify(data)
});

The CSRF token lives in the session. Anonymous sessions (visitor not logged in) expire by default after 5 minutes of inactivity (with_anonymous_session_duration, see Sessions) — a tab left open longer on a public form (/login, /register, etc.) then carries a stale token by the time it's submitted.

Runique handles this at two levels:

• Explicit message: a CSRF failure sets a global error on the form (i18n key csrf.invalid_or_missing), rendered via {% messages %} — never a silent failure.
• Refresh before submission: js/csrf.js intercepts every submission of a form carrying a csrf_token field, does a lightweight GET to the current page to fetch a fresh token (every response carries an X-CSRF-Token header), updates the field, then submits — works even if the session fully expired (the server just issues a new one). The user never loses what they typed, and only sees the CSRF failure if the network is down at the moment of submission. A form stopped by preventDefault() (sent by fetch, a check, a confirmation) is never sent again by this script.

Runique adds this script itself: request.render() inserts a single tag before </body>, with the request's CSP nonce, into every page that carries a CSRF field, whatever wrote it (a Runique form, {% csrf %}, the csrf_field filter or the csrf_token function). A page with several forms gets one tag. Nothing is added to a page without a CSRF field, to a page already loading js/csrf.js, or to a fragment without </body> (HTMX response).

Only a page without a form that sends fetch POSTs, or an HTML response built without request.render(), has to include it itself:

<script {% csp %} src="{% runique_static "js/csrf.js" %}" defer></script>

Some endpoints receive POST requests without a CSRF token — Stripe webhooks, third-party callbacks, JSON APIs called by other servers. Use .csrf_exempt() to bypass CSRF validation on specific paths:

.middleware(|m| {
    m.csrf_exempt(vec!["/webhook/stripe", "/api/callback"])
})

CSRF is always on — there is no .with_csrf() method to call, only the exemption exists.

A POST action with no form (sign-out, a "delete" button) checks the token itself, computed when Request is extracted:

pub async fn logout_view(request: Request) -> AppResult<Response> {
    if !request.prisme.csrf_valid {
        return Ok(StatusCode::FORBIDDEN.into_response());
    }
    logout(&request.session, None).await?;
    Ok(Redirect::to("/").into_response())
}

A native Axum extractor (Form<T>, Json<T> without the header, Multipart) doesn't go through that check: a route using one to write must check the token itself; refusing forms from another site (“Forms sent from another site”, below) doesn't replace it.

Matching is exact — /webhook/stripe does not exempt /webhook/stripe/sub.

After exempting a path, verify the request authenticity by other means in your handler (e.g. Stripe-Signature HMAC-SHA256 for Stripe webhooks).

csrf_exempt() only skips validation — the CSRF token is still generated and available, so a handler on an exempt path can still use Request/RuniqueContext normally (session, template context, …) alongside its own verification logic.