From dab3a70e3ed4620282023f2947dd8c708ac06712 Mon Sep 17 00:00:00 2001 From: Philippe Pittoli Date: Tue, 13 Jun 2023 18:15:47 +0200 Subject: [PATCH] README: add + update + fix most explanations. Sill very much WIP. --- README.md | 81 ++++++++++++++++++++++++++----------------------------- TODO.md | 21 --------------- 2 files changed, 38 insertions(+), 64 deletions(-) diff --git a/README.md b/README.md index 331cbfe..19ed57d 100644 --- a/README.md +++ b/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 -well as shards to fetch dependencies. - -You’ll need the following tools to build authd: +`authd` is written in Crystal. +You’ll need the following tools: - 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 -require "authd" +# Authorization rules -authd = AuthD::Client.new -authd.key = File.read("./some-file").chomp +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 -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. diff --git a/TODO.md b/TODO.md index 32dc614..5677df4 100644 --- a/TODO.md +++ b/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.