authd/README.md

# authd

authd is a token-based authentication micro-service.

> TODO: explain basic concepts behind `authd`.

## Build

`authd` is written in Crystal.
You’ll need the following tools:

  - crystal
  - shards
  - make

To build authd, run the following commands:

```
make
```

## Deployment

```
$ authd --help
```

> TODO: documentation on how to deploy, including with the mail server and tools.

### Users storage

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.

### Administrating users

> TODO: document how to manage users through `authc`.


## APIs

### 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

## 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.