Update documentation

docs/development/architecture.md

@@ -9,10 +9,19 @@ The whole repository is a [Cargo Workspace](https://doc.rust-lang.org/book/ch14-
 
 This includes:
 
- - `oauth2-types`: Useful structures and types to deal with OAuth 2.0/OpenID Connect endpoints. This might end up published as a standalone library as it can be useful in other contexts.
- - `mas-config`: Configuration parsing and loading
- - `mas-core`: Main logic, includes templates, database interactions and HTTP routes
  - `mas-cli`: Command line utility, main entry point
+ - `mas-config`: Configuration parsing and loading
+ - `mas-data-model`: Models of objects that live in the database, regardless of the storage backend
+ - `mas-email`: High-level email sending abstraction
+ - `mas-handlers`: Main HTTP application logic
+ - `mas-iana`: Auto-generated enums from IANA registries
+ - `mas-iana-codegen`: Code generator for the `mas-iana` crate
+ - `mas-jose`: JWT/JWS/JWE/JWK abstraction
+ - `mas-static-files`: Frontend static files (CSS/JS). Includes some frontend tooling
+ - `mas-storage`: Interactions with the database
+ - `mas-tasks`: Asynchronous task runner and scheduler
+ - `mas-warp-utils`: Various filters and utilities for the `warp` web framework
+ - `oauth2-types`: Useful structures and types to deal with OAuth 2.0/OpenID Connect endpoints. This might end up published as a standalone library as it can be useful in other contexts.
 
 ## Important crates
 

docs/development/database.md

@@ -14,7 +14,7 @@ Preparing this flat file is done through `sqlx-cli`, and should be done everytim
 # Install the CLI
 cargo install sqlx-cli --no-default-features --features postgres
 
-cd crates/core/ # Must be in the mas-core crate folder
+cd crates/storage/ # Must be in the mas-storage crate folder
 export DATABASE_URL=postgresql:///matrix_auth
 cargo sqlx prepare
 ```
@@ -24,7 +24,7 @@ cargo sqlx prepare
 Migration files live in the `migrations` folder in the `mas-core` crate.
 
 ```sh
-cd crates/core/ # Again, in the mas-core crate folder
+cd crates/storage/ # Again, in the mas-storage crate folder
 export DATABASE_URL=postgresql:///matrix_auth
 cargo sqlx migrate run # Run pending migrations
 cargo sqlx migrate revert # Revert the last migration

docs/development/warp.md

@@ -1,5 +1,7 @@
 # `warp`
 
+**Warning: this document is not up to date**
+
 Warp has a pretty unique approach in terms of routing.
 It does not have a central router, rather a chain of filters composed together.
 

docs/usage/cli/config.md

@@ -18,14 +18,14 @@ Dump the merged configuration tree.
 ```console
 $ mas-cli config dump --config=first.yaml --config=second.yaml
 ---
-oauth2:
+clients:
   # ...
 ```
 
 ## `config generate`
 
 Generate a sample configuration file.
-It generates random signing keys (`.oauth2.keys`) and the cookie encryption secret (`.cookies.secret`).
+It generates random signing keys (`.secrets.keys`) and the cookie encryption secret (`.secrets.encryption`).
 
 ```console
 $ mas-cli config generate > config.yaml

docs/usage/cli/manage.md

@@ -10,3 +10,7 @@ Register a new user
 $ mas-cli manage register johndoe hunter2
 INFO mas_cli::manage: User registered user=User { id: 2, username: "johndoe" }
 ```
+
+## `manage verify-email <username> <email>`
+
+Mark a user email address as verified

docs/usage/configuration.md

@@ -43,10 +43,12 @@ Check the next section to know about each section.
 database:
   uri: postgresql:///matrix_auth
 
-cookies:
+http:
-  secret: c7e42fb8baba8f228b2e169fdf4c8216dffd5d33ad18bafd8b928c09ca46c718
+  public_base: http://localhost:8080
+
+secrets:
+  encryption: c7e42fb8baba8f228b2e169fdf4c8216dffd5d33ad18bafd8b928c09ca46c718
 
-oauth2:
   keys:
     - type: rsa
       key: |
@@ -91,21 +93,18 @@ oauth2:
 
 ### `http`
 
-Controls on what address the server should be listening on
+Controls the web server.
 
 ```yaml
 http:
+  # On what address and port the server should listen to
   address: 0.0.0.0:8080
-```
 
-### `cookies`
+  # Path from which to serve static files
+  web_root: /var/www/static
 
-Configuration related to encrypted cookies
+  # Public URL base used when building absolute public URLs
-
+  public_base: http://localhost:8080
-```yaml
-cookies:
-  # Secret key used to encrypt cookies
-  secret: c7e42fb8baba8f228b2e169fdf4c8216dffd5d33ad18bafd8b928c09ca46c718
 ```
 
 ### `database`
@@ -149,25 +148,32 @@ templates:
   builtin: true
 ```
 
-### `oauth2`
+### `clients`
 
-Configuration related to the OAuth 2.0 endpoints
+List of OAuth 2.0/OIDC clients and their keys/secrets.
 
 ```yaml
-oauth2:
+clients:
-  # URL where the server should be accessed
+  # Confidential client
-  issuer: http://localhost:8080/
+  - client_id: first
+    client_auth_method: clent_secret_post
+    client_secret: secret
+    # List of authorized redirect URIs
+    redirect_uris:
+      - http://localhost:1234/callback
+  # Public client
+  - client_id: second
+    client_auth_method: none
+```
 
-  # List of OAuth 2.0 clients
+### `secrets`
-  clients:
+
-    # Confidential client
+Signing and encryption secrets
-    - client_id: first
+
-      client_secret: secret
+```yaml
-      # List of authorized redirect URIs
+secrets:
-      redirect_uris:
+  # Encrytion secret (used for encrypting cookies)
-        - http://localhost:1234/callback
+  encryption: c7e42fb8baba8f228b2e169fdf4c8216dffd5d33ad18bafd8b928c09ca46c718
-    # Public client, without client_secret
-    - client_id: second
 
   # Signing keys
   keys:

docs/usage/usage.md

@@ -46,13 +46,11 @@ The OpenID Foundation hosts a OpenID Connect Playground where one can test loggi
 Add the following section to the server configuration file `config.yaml`:
 
 ```yaml
-oauth2:
+clients:
-  # ...
+  - client_id: oidc-playground
-  clients:
+    client_secret: verysecret
-    - client_id: oidc-playground
+    redirect_uris:
-      client_secret: verysecret
+      - "https://openidconnect.net/callback"
-      redirect_uris:
-        - "https://openidconnect.net/callback"
 ```
 
 ### Step 2: Change the playground configuration