vweb.csrf - Provides protection against Cross-site request forgery (CSRF)

for web apps written with vweb

Usage

When building a csrf-protected service, first of all create a structthat implements csrf.App

module main

import vweb
import vweb.csrf

// embeds the csrf.App struct in order to empower the struct to protect against CSRF
struct App {
    csrf.App
}

Start a server e.g. in the main function.

fn main() {
    vweb.run_at(&App{}, vweb.RunParams{
        port: 8080
    }) or { panic(err) }
}

Enable CSRF-protection

Then add a handler-function to define on which route or on which site the CSRF-Token shall be set.

fn (mut app App) index() vweb.Result {

    // Set a Csrf-Cookie (Token will be generated automatically)
    app.set_csrf_cookie()

    // Get the token-value from the csrf-cookie that was just setted
    token := app.get_csrf_token() or { panic(err) }

    return app.text("Csrf-Token set! It's value is: $token")
}

If you want to set the cookies's HttpOnly-status to false in order to make it
accessible to scripts on your site, you can do it like this: app.set_csrf_cookie(csrf.HttpOnly{false}) If no argument is passed the value will be set to true by default.

Protect against CSRF

If you want to protect a route or a site against CSRF just add
app.csrf_protect() at the beginning of the handler-function.

fn (mut app App) foo() vweb.Result {
    // Protect this handler-function against CSRF
    app.csrf_protect()
    return app.text("Checked and passed csrf-guard")
}

struct App {
	vweb.Context
	csrf_cookie_value string
}

fn (mut app App) csrf_protect() CheckedApp

csrf_protect - protects a handler-function against CSRF. Should be set at the beginning of the handler-function.

fn (mut app App) get_csrf_token() ?string

get_csrf_token - returns the CSRF-Token that has been set. Make sure that you set one by using set_csrf_cookie(). If it's value is empty or no cookie has been generated, the function will throw an error.

fn (mut app App) set_csrf_cookie(h ...HttpOnly) App

set_csrf_cookie - generates a CSRF-Token and sets the CSRF-Cookie. It is possible to set the HttpOnly-status of the cookie to false by adding an argument of the HttpOnly-struct like this: app.set_csrf_cookie(csrf.HttpOnly{false}) If no argument is set, http_only will be set to trueby default.

struct HttpOnly {
	http_only bool
}