README: add + update + fix most explanations. Sill very much WIP.

README.md

@@ -2,41 +2,31 @@
 
 authd is a token-based authentication micro-service.
 
+> TODO: explain basic concepts behind `authd`.
+
 ## Build
 
-`authd` is written in Crystal and uses `build.zsh` as Makefile generator, as
+`authd` is written in Crystal.
-well as shards to fetch dependencies.
+You’ll need the following tools:
-
-You’ll need the following tools to build authd:
 
   - crystal
   - shards
-  - build.zsh
   - make
 
 To build authd, run the following commands:
 
 ```
-shards install
 make
 ```
 
-Note that if you clone authd from its repository, its `Makefile` may be missing.
-In such situations, run `build.zsh -c` to generate it, after which `make` should run fine.
-
 ## Deployment
 
 ```
 $ authd --help
-usage: authd [options]
-    -s directory, --storage directory
-                                     Directory in which to store users.
-    -k file, --key-file file         JWT key file
-    -R                               --allow-registrations
-    -h, --help                       Show this help
-$
 ```
 
+> TODO: documentation on how to deploy, including with the mail server and tools.
+
 ### Users storage
 
 The storage directory will default to `./storage`.
@@ -44,29 +34,11 @@ The storage directory will default to `./storage`.
 No SQL database, database management system or other kind of setup is required to run authd and store users.
 
 To migrate an instance of authd, a simple copy of the storage directory will be enough.
-Make sure your copy preserves symlinks, as those are extensively used.
 
 ### Administrating users
 
-The `authd-user-add` and `authd-user-allow` are tools to add users to authd’s database and to edit their permissions.
+> TODO: document how to manage users through `authc`.
 
-The permission level `none` can be used in `authd-user-allow` to remove a permission.
-
-### Key file
-
-authd will provide users with cryptographically signed tokens.
-To sign and check those tokens, a shared key is required between authd and services using authd.
-
-authd reads that key from a file to prevent it being visible on the command line when running authd.
-
-Any content is acceptable as a key file.
-
-Example:
-
-```
-$ echo "I am a key." > key-file
-$ authd -k ./key-file
-```
 
 ## APIs
 
@@ -74,25 +46,48 @@ $ authd -k ./key-file
 
 authd’s protocol is still subject to change.
 
+> TODO: document messages.
+
 ### Libraries
 
+> TODO: document basic functions in the `AuthD::Client` class to exchange messages with `authd`.
+
 A `AuthD::Client` Crystal class is available to build synchronous clients in Crystal.
 
-```crystal
+# Authorization rules
-require "authd"
 
-authd = AuthD::Client.new
+Logged users can:
-authd.key = File.read("./some-file").chomp
+- retrieve public data of any user **individually**
+- change their own data: password, email address, profile entries (except the read-only ones)
+- delete their account
+- check their own permissions
 
-pp! r = authd.get_token?("login", "password")
+Admins with 'Read' permission on the '*' resource can:
+- list users
 
-pp! r = authd.add_user("login", "password")
+Admins with 'Edit' permission on the '*' resource can:
+- change data of another user
 
-pp! u = authd.get_user?("login", "password").not_nil!
+Admins with 'Admin' permission on the '*' resource (or the 'admin' boolean) can:
-```
+- change read-only profile entries and permissions
+- delete a user
+- uprank and downrank admins
 
 ## Contributing
 
 Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
 
 Please make sure to update tests as appropriate.
+
+# WIP: design choices
+
+An user has a number, a login, an email address, a profile (`Hash(String, JSON::Any)`) and permissions.
+An `admin` boolean also tells weither or not the user is an administrator.
+
+**Requests work mostly on current user**.
+Some take a *UserID* to identify another user (its number or its login, both are valid), which often implies admin permissions.
+
+**Permissions** are: None, Read, Edit, Admin.
+Plus, the `admin` boolean value in the `AuthD::User` class.
+
+> TODO: continue explaining design choices.

TODO.md

@@ -8,27 +8,6 @@ A combinaison of both is fine as long as the logic is comprehensively documented
 A simple error message is given instead of specific messages for each recurring error.
 In the same time, some exceptions (such as **AdminAuthenticationException**) are used a few times for the same kind of errors.
 
-Requests work mostly on current user, but some take a *UserID* to identify another user.
-Requests should either always work on current user (which implies to create new requests working on another user) or always take an optional *UserID* parameter.
-
-### Authorization rules
-
-Logged users can:
-- retrieve public data of any user **individually**
-- change their own data: password, email address, profile entries (except the read-only ones)
-- delete their account
-
-Admins with 'Read' permission on the '*' resource can:
-- list users
-
-Admins with 'Edit' permission on the '*' resource can:
-- change data of another user
-
-Admins with 'Admin' permission on the '*' resource (or the 'admin' boolean) can:
-- change read-only profile entries and permissions
-- delete a user
-- uprank and downrank admins
-
 ### Structures, not classes
 
 Maybe in some cases, it could be great to use structures instead of classes.