From 26da4c6327712a681255cf71b0fdc4ecfec53024 Mon Sep 17 00:00:00 2001 From: David Mehren Date: Sun, 19 Mar 2023 17:01:11 +0100 Subject: [PATCH] docs: consistent Markdown formatting Signed-off-by: David Mehren --- docs/content/dev/design_docs/api_auth.md | 4 +++- docs/content/dev/design_docs/user_profiles.md | 3 +++ docs/content/dev/dev_notes.md | 3 +++ 3 files changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/content/dev/design_docs/api_auth.md b/docs/content/dev/design_docs/api_auth.md index 30b00ef08..b040e3ac0 100644 --- a/docs/content/dev/design_docs/api_auth.md +++ b/docs/content/dev/design_docs/api_auth.md @@ -5,6 +5,7 @@ This is a design document, explaining the design and vision for a HedgeDoc 2 feature. It is not a user guide and may or may not be fully implemented. ## Public API + All requests to the public API require authentication using a [bearer token](https://datatracker.ietf.org/doc/html/rfc6750). This token can be generated using the profile page in the frontend @@ -20,6 +21,7 @@ A SHA-512 hash of the secret is stored in the database. To validate tokens, the secret and checks it against the stored hash for the provided identifier. #### Choosing a hash function + Unfortunately, there does not seem to be any explicit documentation about our exact use-case. Most docs describe classic password-saving scenarios and recommend bcrypt, scrypt or argon2. These hashing functions are slow to stop brute-force or dictionary attacks, which would expose the original, @@ -38,7 +40,7 @@ SHA-512 (or alternatively SHA3) fits this use-case. ## Private API The private API uses a session cookie to authenticate the user. -Sessions are handled using passport.js. +Sessions are handled using [passport.js](https://www.passportjs.org/). The backend hands out a new session token after the user has successfully authenticated using one of the supported authentication methods: diff --git a/docs/content/dev/design_docs/user_profiles.md b/docs/content/dev/design_docs/user_profiles.md index e4a1b0016..6385359c6 100644 --- a/docs/content/dev/design_docs/user_profiles.md +++ b/docs/content/dev/design_docs/user_profiles.md @@ -34,6 +34,7 @@ is automatically set as sync source and cannot be changed by the user. This effectively pins the account to this provider. ## Example: Corporate LDAP + The administrator wants to allow users to log in via the corporate LDAP and Google. Login must only be possible for users present in LDAP and all users must be displayed as they are in the LDAP. @@ -52,6 +53,7 @@ the 'add a new login method' feature in their profile page to link their Google account and use it to login afterwards. ## Example: Username Conflict + HedgeDoc is configured with two auth providers. - A user logs in using auth provider A. @@ -68,6 +70,7 @@ HedgeDoc is configured with two auth providers. ### Handling of sync sources and username conflicts #### Global sync sources + If at the time of logging in with auth provider A, *only* A is configured as a *global* sync source, the backend cannot automatically create a user with another username. diff --git a/docs/content/dev/dev_notes.md b/docs/content/dev/dev_notes.md index ad1fab897..6a48f9a97 100644 --- a/docs/content/dev/dev_notes.md +++ b/docs/content/dev/dev_notes.md @@ -1,9 +1,11 @@ # Development Notes + This document collects notes and decisions taken during the development of HedgeDoc 2.0. It should be converted to a properly structured documentation, but having unstructured docs is better than having no docs. ## Supported databases + We intend to officially support and test these databases: - SQLite (for development and smaller instances) @@ -11,6 +13,7 @@ We intend to officially support and test these databases: - MariaDB ## Special Groups + The software provides two special groups which have no explicit users: - `everyone` (Describing that everyone who wants to access a note can do if it is enabled in the config.)