README update (and split).

API.md

@@ -0,0 +1,34 @@
+> This file is still very much a WIP.
+
+### Protocol
+
+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.
+
+### 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
+- check their own permissions
+
+Admins with 'Read' permission on the '*' resource can:
+- list users
+- check permissions of other 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
+- change permissions
+- delete a user
+- uprank and downrank admins

DESIGN-CHOICES.md

@@ -0,0 +1,12 @@
+> This file is still very much a WIP.
+
+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.

README.md

@@ -1,8 +1,12 @@
 # authd
 
-`authd` is a token-based authentication micro-service based on [libipc][libipc].
+`authd` is a (JWT) token-based authentication micro-service based on [libipc][libipc].
+`authd` stores users (login, encrypted password), their profile (arbitrary data) and their *permissions*.
+For example, `authd` is used by [dnsmanagerd][dnsmanagerd] to handle authentication and permissions.
 
-> TODO: explain basic concepts behind `authd`.
+No SQL, the entire database is stored in plain files, thanks to [the DODB database library][dodb].
+
+The [netlibre service][netlibre] is the first to use `authd` in a real-life deployment.
 
 ## Build
 
@@ -20,55 +24,43 @@ make install
 $ authd --help
 ```
 
-> TODO: documentation on how to deploy, including with the mail server and tools.
+For a more extensive documentation, please read the manual for both [authd][authdmanual] and [authctl][authctlmanual].
 
-### Users storage
+See the [configuration example][configuration-example] to avoid long command-line parameters.
 
-The storage directory will default to `./storage`.
+Also, extensive usage examples are available in the makefiles.
 
-No SQL database, database management system or other kind of setup is required to run authd and store users.
+## Administration
 
-To migrate an instance of authd, a simple copy of the storage directory will be enough.
+```sh
+# First user in the database is an administrator.
+authctl bootstrap name email
+```
 
-### Administrating users
+```sh
+# Add a user:
+authctl user add login email
+```
 
-> TODO: document how to manage users through `authctl`.
+For a comprehensive list of available commands, please read the [authctl manual][authctlmanual].
 
+## Real-life deployment
 
-## APIs
+For a real-life deployment, you might want to enable registration.
+In this case, you need to get a `mailer` application to send template emails.
+See [an example of such application][mailer].
 
-### Protocol
+### Backup and migration
 
-authd’s protocol is still subject to change.
+```sh
+# Database backup.
+tar cfz db.tar.gz ./db-authd
 
-> TODO: document messages.
+# Database migration.
+tar xfz db.tar.gz
+```
 
-### 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.
-
-# 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
-- check their own permissions
-
-Admins with 'Read' permission on the '*' resource can:
-- list users
-- check permissions of other 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
-- change permissions
-- delete a user
-- uprank and downrank admins
+Wasn't that hard, isn't it?
 
 ## Contributing
 
@@ -76,19 +68,17 @@ Pull requests are welcome. For major changes, please open an issue first to disc
 
 Please make sure to update tests as appropriate.
 
-# WIP: design choices
+# API and 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.
+See [API.md][API] and [DESIGN-CHOICES.md][design].
 
 [libipc]: https://git.baguette.netlib.re/Baguette/libipc
 [dnsmanagerd]: https://git.baguette.netlib.re/Baguette/dnsmanagerd
-[netlibre]: https://netlib.re
+[netlibre]: https://www.netlib.re
+[configuration-example]: ./configuration-example.yml
+[mailer]: https://git.baguette.netlib.re/Baguette/mailer
+[authdmanual]: ./man/authd.1
+[authctlmanual]: ./man/authctl.1
+[dodb]: https://git.baguette.netlib.re/Baguette/dodb.cr
+[API]: ./API.md
+[design]: ./DESIGN-CHOICES.md

TODO.md

@@ -8,11 +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.
 
-### New features
-
-- On login: inform the user he doesn't have an email address.
-  This happens when the user was migrated.
-
 ### Structures, not classes
 
 Maybe in some cases, it could be great to use structures instead of classes.

configuration-example.yml

@@ -0,0 +1,50 @@
+# Login and password so `authctl` can be authenticated to `authd`.
+login: admin
+pass: secret
+
+# In case you have a special `mailer` application.
+# Read the manual to understand how it is invoked.
+mailer_exe: /usr/local/bin/my-special-mailer
+
+# File used as password to encrypt user passwords.
+secret_key_file: /var/authd/password
+
+# Path to the database.
+storage_directory: /var/authd/db
+
+# Does symlinks have to be recreated each time the app starts?
+#recreate_indexes: false
+
+# Are registrations open? Does it require an email?
+registrations: true
+require_email: true
+
+# Name of the email templates for account activation and password recovery.
+activation_template: netlibre-email-activation
+recovery_template:   netlibre-email-recovery
+
+# Name of the `authd` IPC service.
+#service_name: auth
+
+# Read-only user profile keys (to prevent modification from third-parties).
+#read_only_profile_keys: []
+
+#
+# Verbosity-related options.
+#
+
+#verbosity: 4
+
+#print_password_recovery_parameters: false
+
+# IPC-related variables. By default, only print errors and exceptions.
+#print_ipc_timer:            false
+#print_ipc_connection:       false
+#print_ipc_disconnection:    false
+#print_ipc_extra_socket:     false
+#print_ipc_message_received: false
+#print_ipc_message_sent:     false
+#print_ipc_switch:           false
+#print_ipc_error:            true
+#print_ipc_exception:        true
+#print_keepalive:            false

man/authctl.1

@@ -120,9 +120,9 @@ Operations on users.
 .Nm authctl
 .Ar user No
 .Ar subcommand No
-
-.Ar subcommand : No
+.br
 .in +4
+Subcommands:
 .Bl -tag -width "change-password" -compact
 .It Li add
 Adding a user to the DB.