feat: documentation for web authentication (login, verification)

Signed-off-by: Kevin Morris <kevr@0cost.org>

doc/web-auth.md

@@ -0,0 +1,111 @@
+# aurweb Web Authentication
+
+aurweb uses an HTTP cookie to persist user sessions across requests.
+This cookie **must** be delivered with a request in order to be considered
+an authenticated user.
+
+See [HTTP Cookie](#http-cookie) for detailed information about the cookie.
+
+## HTTP Cookie
+
+aurweb utilizes an HTTP cookie by the name of `AURSID` to track
+user authentication across requests.
+
+This cookie's requirements changes due to aurweb's configuration
+in the following ways:
+
+- `options.disable_http_login: 0`
+    - [Samesite=LAX](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#samesite_attribute), Max-Age
+- `options.disable_http_login: 1`
+    - [Secure, HttpOnly](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#restrict_access_to_cookies), [Samesite=Strict](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#samesite_attribute), Max-Age
+
+### Max-Age
+
+The value used for the `AURSID` Max-Age attribute is decided based
+off of the "Remember Me" checkbox on the login page. Both paths
+use their own independent configuration for the number of seconds
+that each type of session should stay alive.
+
+- "Remember Me" unchecked while logging in
+    - `options.login_timeout` is used
+- "Remember Me" checked while logging in
+    - `options.persistent_cookie_timeout` is used
+
+Both `options.login_timeout` and `options.persistent_cookie_timeout`
+indicate the number of seconds the session should live.
+
+### Notes
+
+At all times, aur.archlinux.org operates over HTTPS. Secure cookies will
+only remain intact when subsequently requesting an aurweb route through
+the HTTPS scheme at the same host as the cookie was obtained.
+
+## Login Process
+
+When a user logs in to aurweb, the following steps are taken:
+
+1. Was a Referer header delivered from an address starting with
+`{aurweb_url}/login`?
+    1. No, an HTTP 400 Bad Request response is returned
+    2. Yes, move on to 2
+2. Does a Users database record exist for the given username/email?
+    1. No, you are returned to the login page with `Bad username or password.`
+    error
+    2. Yes, move on to 3
+3. Is the user suspended?
+    1. Yes, you are returned to the login page with `Account Suspended` error
+    2. No, move on to 4
+4. Can the user login with the given password?
+    1. No, you are returned to the login page with `Bad username or password.`
+    error
+    2. Yes, move on to 5
+5. Update the user's `LastLogin` and `LastLoginIPAddress` columns
+6. Does the user have a related Sessions record?
+    1. No, generate a new Sessions record with a new unique `SessionID`
+    2. Yes, update the Sessions record's `SessionID` column with a new unique
+    string and update the Sessions record's `LastUpdateTS` column if it has
+    expired
+    3. In both cases, set the user's `InactivityTS` column to `0`
+    4. In both cases, return the new `SessionID` column value and move on to 7
+7. Return a redirect to the `next` GET variable with the
+following cookies set:
+    1. `AURSID`
+        - Unique session string matching the user's related
+        `Sessions.SessionID` column
+    2. `AURTZ`
+        - User's timezone setting
+    3. `AURLANG`
+        - User's language setting
+    4. `AURREMEMBER`
+        - Boolean state of the "Remember Me" checkbox when login submitted
+
+## Auth Verification
+
+When a request is made toward aurweb, a middleware is responsible for
+verifying the user's auth cookie. If no valid `AURSID` cookie could be
+found for a user in the database, the request is considered unauthenticated.
+
+The following list of steps describes exactly how this verification works:
+1. Was the `AURSID` cookie delivered?
+    1. No, the algorithm ends, you are considered unauthenticated
+    2. Yes, move on to 2
+2. Was the `AURREMEMBER` cookie delivered with a value of 1?
+    1. No, set the expected session timeout **T** to `options.login_timeout`
+    2. Yes, set the expected session timeout **T** to
+    `options.persistent_cookie_timeout`
+3. Does a Sessions database record exist which matches the `AURSID`?
+    1. No, the algorithm ends, you are considered unauthenticated
+    2. Yes, move on to 4
+4. Does the Sessions record's LastUpdateTS column fit within `utcnow - T`?
+    1. No, the Sessions record at hand is deleted, the algorithm ends, you
+    are considered unauthenticated
+    2. Yes, move on to 5
+5. You are considered authenticated
+
+## aur.archlinux.org Auth-Related Configuration
+
+- Operates over HTTPS with a Let's Encrypt SSL certificate
+- `options.disable_http_login: 1`
+- `options.login_timeout: <default_provided_in_config.defaults>`
+- `options.persistent_cookie_timeout: <default_provided_in_config.defaults>`
+