From 44c47b3c2a2ec3e9c9c0efac4dceaec082a62d60 Mon Sep 17 00:00:00 2001
From: metamuffin <metamuffin@disroot.org>
Date: Thu, 30 May 2024 00:06:08 +0200
Subject: document cookie auth and such

---
 readme.md | 64 +++++++++++++++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 54 insertions(+), 10 deletions(-)

(limited to 'readme.md')

diff --git a/readme.md b/readme.md
index 2ad4faa..cfd40bd 100644
--- a/readme.md
+++ b/readme.md
@@ -4,11 +4,14 @@ a simple stupid reverse proxy
 
 ## Features
 
+- HTTP/1.1
 - Simple to configure (see below)
-- Handles connection upgrades correctly by default (websocket, etc.)
 - Composable modules
+- Handles connection upgrades correctly by default (websocket, etc.)
 - TLS support
-- _TODO: h2; match on uris; connection pooling_
+- Configuration hot-reloading
+- Client authentification (http basic auth, cookie)
+- _TODO: h2; h3; match on uris; connection pooling; custom connection timeouts_
 
 ## Quick Start
 
@@ -36,11 +39,13 @@ handler: !hosts
         index: true
     
     "panel.mydomain.com": !access_log
-
 ```
 
 ## Reference
 
+The configuration uses YAML formatting. When the configuration file is changed,
+it will automatically be loaded and applied if valid.
+
 - **section `http`**
   - `bind`: string or list of strings with addresses to listen on.
 
@@ -67,6 +72,9 @@ handler: !hosts
 
 ### Modules
 
+Modules handle requests. Some of them have arguments which are modules
+themselves; in that case the request is passed on.
+
 - **module `hosts`**
   - Hands over the requests to different modules depending on the `host` header.
   - Takes a map from hostname (string) to handler (module)
@@ -86,13 +94,12 @@ handler: !hosts
   - `root`: root directory to be served (string)
   - `index`: enables directory indexing (boolean)
 
-- **module `http_basic_auth`**
-  - Filters requests via HTTP Basic Authentification. Unauthorized clients will
-    be challenged on every request.
-  - `realm`: describes what the user is logging into (most modern browsers dont show this anymore -_-)
-  - `valid`: list of valid logins (string) in the format `<username>:<password>`
-    (password in plain text). TODO: hashing
-  - `next`: a module to handle this request on successfully authentificated. (module)
+- **module `file`**
+  - Replies with static content.
+  - `path`: file path to the content. _This will be loaded into memory once!_
+    (string)
+  - `content`: inline declaration of the content. (string)
+  - `type`: type of content reflected in `content-type` header. (string)
 
 - **module `access_log`**
   - Logs requests to a file.
@@ -105,6 +112,43 @@ handler: !hosts
   - Rejects every request with a custom error message.
   - Takes an error message (string)
 
+- **module `http_basic_auth`**
+  - Filters requests via HTTP Basic Authentification. Unauthorized clients will
+    be challenged on every request.
+  - `realm`: describes what the user is logging into (most modern browsers dont
+    show this anymore -_-)
+  - `users`: list of valid logins (credentials)
+  - `next`: a module to handle this request on successfully authentificated.
+    (module)
+
+- **module `cookie_auth`**
+  - Authentificates a client based on cookies. The cookies are set on login by a
+    POST request to `/_gnix_login` with form fields `password` and `username`
+    (optional, default: "user") in `x-www-form-urlencoded` format. In any case
+    the users submitting this request will be directed back to the page they
+    come from. Successful logins set two cookies: `gnix_username` containing the
+    username and `gnix_auth` containing an opaque authentification token. The
+    `gnix_username` cookie is authentificated by gnix and can therefore be used
+    by applications.
+  - `users`: list of valid logins (credentials)
+  - `expire`: seconds before logins expire; not setting this option keeps the
+    login valid forever on the server but cleared after the session on the
+    client (optional number)
+  - `secure`: makes the cookies accessable from secure contexts exclusively i.e.
+    HTTPS (boolean)
+  - `next`: a module to handle this request on successfully authentificated.
+    (module)
+  - `fail`: a module to handle the request when a user is not authorized. This
+    could show an HTML form prompting the user to log in. An implementation of
+    such a form is provided with the distribution of this software, usually in
+    `/usr/share/gnix/login.html`
+
+#### Credentials config format
+
+Login credentials for `cookie_auth` and `http_basic_auth` are supplied as either
+an object mapping usernames to PHC strings or a file path pointing to a file
+that contains that map in YALM format.
+
 ## License
 
 AGPL-3.0-only; see [COPYING](./COPYING)
-- 
cgit v1.2.3-70-g09d2