From 9641ced901b22d735322d061bc91049e22d67b2b Mon Sep 17 00:00:00 2001
From: flopetautschnig <69145145+floscodes@users.noreply.github.com>
Date: Thu, 8 Sep 2022 12:20:29 +0200
Subject: [PATCH] vweb.csrf: add a README.md, correct doc comments for public
 functions (#15697)

---
 vlib/vweb/csrf/README.md       | 66 ++++++++++++++++++++++++++++++++++
 vlib/vweb/csrf/create_cookie.v |  4 +--
 2 files changed, 68 insertions(+), 2 deletions(-)
 create mode 100644 vlib/vweb/csrf/README.md

diff --git a/vlib/vweb/csrf/README.md b/vlib/vweb/csrf/README.md
new file mode 100644
index 0000000000..1cc23662d4
--- /dev/null
+++ b/vlib/vweb/csrf/README.md
@@ -0,0 +1,66 @@
+# 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 `struct`that implements `csrf.App`
+
+```v ignore
+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.
+
+```v ignore
+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.
+
+```v ignore
+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.
+
+```v ignore
+fn (mut app App) foo() vweb.Result {
+    // Protect this handler-function against CSRF
+	app.csrf_protect()
+	return app.text("Checked and passed csrf-guard")
+}
+```
+
+
diff --git a/vlib/vweb/csrf/create_cookie.v b/vlib/vweb/csrf/create_cookie.v
index e23e9fed06..5584fe0b49 100644
--- a/vlib/vweb/csrf/create_cookie.v
+++ b/vlib/vweb/csrf/create_cookie.v
@@ -6,7 +6,7 @@ const chars = 'QWERTZUIOPASDFGHJKLYXCVBNMqwertzuiopasdfghjklyxcvbnm1234567890_-'
 
 const cookie_key = '__Host-Csrf-Token'
 
-// set_csrf_cookie - generates a CSRF-Token and sets the CSRF-Cookie. It is possible to set the http-only-status of the cookie to false by adding an argument of the HttpOnly-struct like this:
+// 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 `true`by default.
 pub fn (mut app App) set_csrf_cookie(h ...HttpOnly) App {
@@ -44,7 +44,7 @@ fn create_cookie(h bool) CsrfCookie {
 	}
 }
 
-// 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 thor an error.
+// 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.
 pub fn (mut app App) get_csrf_token() ?string {
 	if app.csrf_cookie_value != '' {
 		return app.csrf_cookie_value