From d35cc5eda2cb20f7ad231505ebe1a82d80efba38 Mon Sep 17 00:00:00 2001 From: octycs Date: Wed, 18 Mar 2020 18:20:10 +0100 Subject: [PATCH] Add Readme for server and frontend --- frontend/Readme.md | 3 +++ server/Readme.md | 56 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 59 insertions(+) create mode 100644 frontend/Readme.md create mode 100644 server/Readme.md diff --git a/frontend/Readme.md b/frontend/Readme.md new file mode 100644 index 0000000..2fcb923 --- /dev/null +++ b/frontend/Readme.md @@ -0,0 +1,3 @@ +# Frontend +The web frontend of the keytracker is a very simple single page app that uses the keytracker API via JS. +It can be statically hosted, though you might need to consider configuring CORS on the server. diff --git a/server/Readme.md b/server/Readme.md new file mode 100644 index 0000000..dec0f00 --- /dev/null +++ b/server/Readme.md @@ -0,0 +1,56 @@ +# Keytracker Backend +This is the keytracker backend. It provides a stateless HTTP API for the Website and the Telegram Bot. + +## Installation & Configuration +The backend is written in Python based on [Flask](https://flask.palletsprojects.com). +See [here](https://flask.palletsprojects.com/en/1.1.x/installation/) for installation instructions. +For development purpuses you can start the server with `python3 server.py`, however for production +you should use a instead ([Flask Deployment](https://flask.palletsprojects.com/en/1.1.x/tutorial/deploy/)). + +The configuration is in `config`. An example configuration is provided in `example-config`. Start of by +copying the example config: `cp example-config config` and edit to your needs. + +### Adding a key +The keys are configured in the config file in the `Keys` section. There is one line for each key. +You can use the script `generate_key.py` to generate the configuration line. +Please note that (as of now) not all changes are automatically synced to the database. +Adding a key is no problem, however (as of now, this is a TODO) deleting a key is not yet supported: +The token and history remain in the database and can still be used, however it is no longer possible +to retrieve the key name and get a new auth token to query the keyholder. +Changing the key name does also automatically update as the key name is not stored in the database. +The same applies for the password. Note that when the password is changed all users that already +have access to the keyholder data keep their access (The auth token remain valid) +Changing the key id is equivalent to adding a new key and deleting the old key. +Changing the claim token will automatically add the new token to the database, however the old token +will not automatically be invalidated. To invalidate the old key (e.g. to invalidate a QR code), +you can simply delete the old claim token from the database. + +## API Documentation +You can use the API by GET and POST requests to `your-api-url.com/`. +All requests are stateless, that means there are no sessions. Authentication is implemented with the +`X-Auth-Token` HTTP header which you need to provide on every request. + +*/auth* (POST) +Request an auth token to query the keyholder. You need to provide that password in the `pass` POST data. +Note that you must also provide an already valid token (usually the claim token). + +*/claim* (POST) +Claim a key (which key is automatically determined by your token). The POST data must contain the `name` +and `contact` as string with a length of at least two characters. This request returns a claim id. +You can use it to find out whether you are still the current keyholder. + +*/keyholder* (GET) +Return up to 3 of the latest keyholder as JSON list (first element is the current keyholder): +`[{"name": "", "contact": "", "timestamp": }, ...]`. +If the auth token is not allowed to query the keyholder a 403 error is returned. + +*/status/* (GET) +Query whether the given claim is still the latest. This is the only request that does not require a token. +It may return the following values: +`unknown` - the claim id is unknown +`latest` - the claim is the latest claim for the associated key +`outdated` - the claim is no longer the latest for the associated key + +*/keyname* (GET) +Retrieve the name of the key associated to the used token. If the key is unknown or the token is +invalid the response is empty.