From ab395730eb93ec405046ab0f81475f48b45daa00 Mon Sep 17 00:00:00 2001 From: inexcode Date: Wed, 16 Feb 2022 17:03:30 +0300 Subject: [PATCH] API 1.2.0 --- src/rest-api/auth.md | 145 +++++++++++++++++++++++++++++++++++++ src/rest-api/changelog.md | 11 ++- src/rest-api/migrations.md | 6 +- 3 files changed, 157 insertions(+), 5 deletions(-) diff --git a/src/rest-api/auth.md b/src/rest-api/auth.md index 192ffc6..a3fc052 100644 --- a/src/rest-api/auth.md +++ b/src/rest-api/auth.md @@ -4,6 +4,151 @@ At that time, only one access token could be used. It is declared during nixos-i ## After 1.2.0 New auth system was introduced in 1.2.0. See [[migrations#Create tokens JSON file]] for details on migration to the new system. ### Tokens storage +Tokens are stored in `/etc/nixos/userdata/tokens.json`, which can be accessed only by root. +File follows this schema: +```json +{ + "$schema": "http://json-schema.org/schema#", + "$id": "https://git.selfprivacy.org/inex/selfprivacy-nixos-config/raw/branch/master/userdata/tokens_schema.json", + "type": "object", + "properties": { + "tokens": { + "type": "array", + "items": { + "type": "object", + "properties": { + "token": { + "type": "string" + }, + "name": { + "type": "string" + }, + "date": { + "type": "string" + } + }, + "required": [ + "token", + "name", + "date" + ] + } + }, + "recovery_token": { + "type": "object", + "properties": { + "token": { + "type": "string" + }, + "date": { + "type": "string" + }, + "expiration": { + "type": "string" + }, + "uses_left": { + "type": "integer" + } + }, + "required": [ + "token", + "date" + ] + }, + "new_device": { + "type": "object", + "properties": { + "token": { + "type": "string" + }, + "date": { + "type": "string" + }, + "expiration": { + "type": "string" + } + }, + "required": [ + "token", + "date", + "expiration" + ] + } + }, + "required": [ + "tokens" + ] +} +``` +i.e.: +```json +{ + "tokens": [ + { + "token": "device token", + "name": "device name", + "date": "date of creation", + } + ], + "recovery_token": { + "token": "recovery token", + "date": "date of creation", + "expiration": "date of expiration", + "uses_left": "number of uses left" + }, + "new_device": { + "token": "new device auth token", + "date": "date of creation", + "expiration": "date of expiration", + } +} +``` +All dates MUST follow the `%Y-%m-%dT%H:%M:%S.%fZ` format. ### Token control +Refer to the API documentation. +You can list the tokens and delete tokens. + ### New device token creation +To authorize a new device, existing authorized device must acquire a new device token. + +POST `/auth/new_device` is used without any arguments. + +New device tokens are 16 random bytes encoded to the mnemonic phrase. Token lifetime is 10 minutes or less. There can only be one token for new device auth. + +This token is used by the new device to get a proper access token. + +POST `/auth/new_device/authorize` is used with two arguments: +- `token` is the new device token. + - If new device token is incorrect, does not exist of expired, 404 error is returned +- `device` is the device name. + - If the name already taken, random suffix will be added. + +```mermaid +sequenceDiagram + actor A as Authorized device + participant Server + actor B as New device + A->>+Server: /auth/new_device + Server-->>A: Mnemonic token + Note over A,B: Mnemonic token is used by new device to get access token + B->>Server: /auth/new_device/authorize + Server-->>-B: Access token +``` ### Recovery token +Recovery tokens are 24 random bytes encoded to the mnemonic phrase. Optionally, token lifetime and allowed uses can be limited. + +Only one recovery token can exist at a time. If a new token is generated, the old one is deleted. + +POST `/auth/recovery_token` is used to generate a recovery token. There are two *optional* arguments: +- `expiration` is the datetime when token must expire. + - MUST follow the `%Y-%m-%dT%H:%M:%S.%fZ` format. + - Returns 400 if time format is incorrect + - Returns 400 if date is in the past +- `uses` is how many times the recovery token can be used + - MUST be 1 or more. + +POST `/auth/recovery_token/use` to use the token. Two required arguments: +- `token` is the recovery token + - If recovery token is incorrect, does not exist of expired, 404 error is returned +- `device` is the device name + - If the name already taken, random suffix will be added. \ No newline at end of file diff --git a/src/rest-api/changelog.md b/src/rest-api/changelog.md index 7c2ea4a..2146db1 100644 --- a/src/rest-api/changelog.md +++ b/src/rest-api/changelog.md @@ -1,11 +1,18 @@ # Changelog -## authorization_tokens branch +## 1.2.0 - Added authorization tokens module to allow - Having more than one device controlling the server - Refreshing the current token - Obtaining a recovery token ### API changes -- +- `/auth/tokens` added +- `/auth/new_device` added +- **Public endpoint** `/auth/new_device/authorize` added. +- `/auth/recovery_token` added +- **Public endpoint** `/auth/recovery_token/use` added. +### New migrations +- [[migrations#Create tokens JSON file|Migrate to new tokens storage]] + ## 1.1.1 Released on 26 Jan 2022 diff --git a/src/rest-api/migrations.md b/src/rest-api/migrations.md index 87f2085..bd3076f 100644 --- a/src/rest-api/migrations.md +++ b/src/rest-api/migrations.md @@ -40,11 +40,11 @@ Git repository at `/etc/nixos` is using `rolling-testing` branch. ## Create tokens JSON file **Migration ID**: `create_tokens_json` -**Introduced in**: [[changelog#authorization_tokens branch]] +**Introduced in**: [[changelog#1 2 0|v1.2.0]] ### Description -Selfprivacy API used a single token in userdata.json for authentication. -This migration creates a new tokens.json file with the old token in it. +Selfprivacy API used a single token in `userdata.json` for authentication. +This migration creates a new `tokens.json` file with the old token in it. ### Run conditions `/etc/nixos/userdata/tokens.json` does not exist.