From 676ef29aa094e07ff1f174994641d7fbd84039d0 Mon Sep 17 00:00:00 2001 From: Radical Date: Fri, 2 May 2025 11:53:11 +0200 Subject: [PATCH 1/5] docs: use a proper access token --- API/client-server/v1/friend-request.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/API/client-server/v1/friend-request.md b/API/client-server/v1/friend-request.md index 8d22e1a..798bb0a 100644 --- a/API/client-server/v1/friend-request.md +++ b/API/client-server/v1/friend-request.md @@ -9,7 +9,7 @@ Sends a friend request to the given user. Friend requests can be accepted by hav ## Request | Name | Type | Description | -|--------------|--------|------------------------------------------------------------------------------------------------| +| ------------ | ------ | ---------------------------------------------------------------------------------------------- | | access_token | string | **Required**: The user's auth token. | | uuid | string | **Required**: The UUID of the user they want to befriend. | | server | string | The instance that user is on, can be left out if it's a local friend request. | @@ -17,7 +17,7 @@ Sends a friend request to the given user. Friend requests can be accepted by hav ```json { - "access_token": "gwLhWXD9wrqL3DwxXZ0VHUeOjr8am1yO", + "access_token": "85b2afece430e0e924f2d4277324c868", "uuid": "dcb445f1-16e7-4cd9-ac19-af07acaeb865", "server": "gorb.app", "message": "Heyo, Kira here" From 3d111b35e3adb61b91a02100da190077dcc40b2a Mon Sep 17 00:00:00 2001 From: Radical Date: Fri, 2 May 2025 11:54:04 +0200 Subject: [PATCH 2/5] docs: match login and register to backend --- API/client-server/v1/auth/login.md | 64 +++++++++++++++++++++ API/client-server/v1/{ => auth}/register.md | 52 ++++++++++------- API/client-server/v1/login.md | 57 ------------------ 3 files changed, 95 insertions(+), 78 deletions(-) create mode 100644 API/client-server/v1/auth/login.md rename API/client-server/v1/{ => auth}/register.md (58%) delete mode 100644 API/client-server/v1/login.md diff --git a/API/client-server/v1/auth/login.md b/API/client-server/v1/auth/login.md new file mode 100644 index 0000000..d84d598 --- /dev/null +++ b/API/client-server/v1/auth/login.md @@ -0,0 +1,64 @@ +POST /v1/auth/login + +--- + +Authenticates the user, and issues an access token for future requests. + +--- + +## Request + +| Name | Type | Description | +| ----------- | ------ | ------------------------------------------------------------------------------ | +| username | string | **Required**: Can be the Gorb ID or email of the user trying to log in | +| password | string | **Required**: The user's password in SHA3-384. | +| device_name | string | **Required**: Name to help the user identify the device in their session list. | + +```json +{ + "user_id": "radial_4740", + "password": "f324cbd421326a2abaedf6f395d1a51e189d4a71c755f531289e519f079b224664961e385afcc37da348bd859f34fd1c", + "device_name": "Laptop" +} +``` + +--- + +## Responses + +| Status | Description | +|--------|-------------------------------------------------| +| 200 | Authentication successful. | +| 400 | The post request included poorly formated data. | +| 403 | Part of the cridentials are invalid. | +| 500 | An unhandled error occured. | + +--- + +### 200 + +| Name | Type | Description | +| ------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------- | +| access_token | string | **Required**: The access token that will be used for further authentication. | +| refresh_token | string | The refresh token that will be used to refresh the access token. Required for avoiding users having to log in after access token expiration. | + +```json +{ + "access_token": "85b2afece430e0e924f2d4277324c868", + "refresh_token": "aeb343482fcee3a293e887f5dc840ea8b0fc6b54a26c2584a95a5bc91ff4a749" +} +``` + +--- + +### 500 + +| Name | Type | Description | +| ----- | ------ | -------------------------------- | +| error | string | The error the server encountered | + +```json +{ + "error": "Something went wrong!", +} +``` diff --git a/API/client-server/v1/register.md b/API/client-server/v1/auth/register.md similarity index 58% rename from API/client-server/v1/register.md rename to API/client-server/v1/auth/register.md index 2b88b0f..fb950a9 100644 --- a/API/client-server/v1/register.md +++ b/API/client-server/v1/auth/register.md @@ -1,4 +1,4 @@ -POST /v1/register +POST /v1/auth/register --- @@ -8,18 +8,18 @@ Registers the user, and issues an access token for future requests. ## Request -| Name | Type | Description | -|-------------|--------|-----------------------------------------------------------------------------------------------------------------| -| identifier | string | **Required** User's desired ID. | -| email | string | **Required** User's email. | -| password | string | **Required**: The user's password (we need to figure out how exactly we're hashing + salting it on the client). | -| device_name | string | Name to help the user identify the device in their session list. | +| Name | Type | Description | +| ----------- | ------ | ------------------------------------------------------------------------------ | +| identifier | string | **Required** User's desired ID. | +| email | string | **Required** User's email. | +| password | string | **Required**: The user's password in SHA3-384. | +| device_name | string | **Required**: Name to help the user identify the device in their session list. | ```json { "identifier": "radial_4740", "email": "radial_4740@yahoo.com", - "password": "9r89mhs4czu4", + "password": "f324cbd421326a2abaedf6f395d1a51e189d4a71c755f531289e519f079b224664961e385afcc37da348bd859f34fd1c", "device_name": "Laptop" } ``` @@ -39,21 +39,15 @@ Registers the user, and issues an access token for future requests. ### 200 -| Name | Type | Description | -|---------------|--------|--------------------------------------------------------------------------------------------------------------------------------------------------| -| access_token | string | **Required**: The JWT access token that will be used for further authentication. | -| user_id | string | **Required**: The account's local gorb ID. | -| uuid | string | **Required**: The account's UUID. | -| expires_in | int | How many seconds until the token expires and is invalidated. | -| refresh_token | string | The JWT refresh token that will be used to refresh the access token. Required for avoiding users having to log in after access token expiration. | +| Name | Type | Description | +| ------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------- | +| access_token | string | **Required**: The access token that will be used for further authentication. | +| refresh_token | string | The refresh token that will be used to refresh the access token. Required for avoiding users having to log in after access token expiration. | ```json { - "access_token": "13aa5fe2ae5874fb9616e68c25632a146552584ac238a3e4ede08174fbfc4f45", - "user_id": "radial_4740", - "uuid": "dcb445f1-16e7-4cd9-ac19-af07acaeb865", - "expires_in": 86400, - "refresh_token": "8556a85b8912a78572cd67b21350e188039f656a0781dab20fab7b72a11d2a93" + "access_token": "85b2afece430e0e924f2d4277324c868", + "refresh_token": "aeb343482fcee3a293e887f5dc840ea8b0fc6b54a26c2584a95a5bc91ff4a749" } ``` @@ -62,12 +56,13 @@ Registers the user, and issues an access token for future requests. ### 403 | Name | Type | Description | -|-----------------------------|------|--------------------------------------------------------------------------------| +| --------------------------- | ---- | ------------------------------------------------------------------------------ | | signups_enabled | bool | Does the server have signups enabled? | | gorb_id_valid | bool | Is the given gorb ID even valid? | | gorb_id_available | bool | Is the given gorb ID available? | | email_valid | bool | Is the given email valid? | | email_available | bool | Is the given email available? | +| password_hashed | bool | Is the password hashed using SHA3-384? | | password_minimum_length | bool | Is the given password long enough? | | password_special_characters | bool | If enforced by the server, is there enough special characters in the password? | | password_letters | bool | If enforced by the server, is there enough letters in the password? | @@ -80,9 +75,24 @@ Registers the user, and issues an access token for future requests. "gorb_id_available": true, "email_valid": true, "email_available": false, + "password_hashed": true, "password_minimum_length": true, "password_special_characters": false, "password_letters": true, "password_numbers": true } ``` + +--- + +### 500 + +| Name | Type | Description | +| ----- | ------ | -------------------------------- | +| error | string | The error the server encountered | + +```json +{ + "error": "Something went wrong!", +} +``` diff --git a/API/client-server/v1/login.md b/API/client-server/v1/login.md deleted file mode 100644 index b4d8c17..0000000 --- a/API/client-server/v1/login.md +++ /dev/null @@ -1,57 +0,0 @@ -POST /v1/login - ---- - -Authenticates the user, and issues an access token for future requests. - ---- - -## Request - -| Name | Type | Description | -|-------------|--------|-----------------------------------------------------------------------------------------------------------------| -| user_id | string | User's gorb ID. One of identifier and email **must** be implemented. | -| email | string | User's email. One of identifier and email **must** be implemented. | -| password | string | **Required**: The user's password (we need to figure out how exactly we're hashing + salting it on the client). | -| device_name | string | Name to help the user identify the device in their session list. | - -```json -{ - "user_id": "radial_4740", - "password": "9r89mhs4czu4", - "device_name": "Laptop" -} -``` - ---- - -## Responses - -| Status | Description | -|--------|-------------------------------------------------| -| 200 | Authentication successful. | -| 400 | The post request included poorly formated data. | -| 403 | Part of the cridentials are invalid. | -| 500 | An unhandled error occured. | - ---- - -### 200 - -| Name | Type | Description | -|---------------|--------|----------------------------------------------------------------------------------------------------------------------------------------------| -| access_token | string | **Required**: The access token that will be used for further authentication. | -| user_id | string | **Required**: The account's local gorb ID. | -| uuid | string | **Required**: The account's UUID. | -| expires_in | int | How many seconds until the token expires and is invalidated. | -| refresh_token | string | The refresh token that will be used to refresh the access token. Required for avoiding users having to log in after access token expiration. | - -```json -{ - "access_token": "35e404d160b0eac766cb85cf513670baa627d1e918c4813c3f099e31de300b63", - "user_id": "radial_4740", - "uuid": "dcb445f1-16e7-4cd9-ac19-af07acaeb865", - "expires_in": 86400, - "refresh_token": "d9ce91b7b643d5580ea605ad09ba1e13aef704c412194c00c592b96a62049587" -} -``` From 37309f461b17cee925ff924a6ddd9c58e4eceecc Mon Sep 17 00:00:00 2001 From: Radical Date: Fri, 2 May 2025 11:54:56 +0200 Subject: [PATCH 3/5] docs: add user endpoint from backend endpoint returns information about users using user/UUID or the special user/me endpoint --- API/client-server/v1/user.md | 64 ++++++++++++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) create mode 100644 API/client-server/v1/user.md diff --git a/API/client-server/v1/user.md b/API/client-server/v1/user.md new file mode 100644 index 0000000..4c1d53d --- /dev/null +++ b/API/client-server/v1/user.md @@ -0,0 +1,64 @@ +POST /v1/user/me +POST /v1/user/{UUID} + +--- + +Gathers information about the requested user. + +--- + +## Request + +| Name | Type | Description | +| ------------ | ------ | ------------------------------------ | +| access_token | string | **Required**: The user's auth token. | + + +```json +{ + "access_token": "85b2afece430e0e924f2d4277324c868", +} +``` + +--- + +## Responses + +| Status | Description | +| ------ | ----------------------------------------------- | +| 200 | User data found. | +| 400 | The post request included poorly formated data. | +| 403 | Invalid access token. | +| 500 | An unhandled error occured. | + +--- + +### 200 + +| Name | Type | Description | +| ------------ | ------ | ---------------------------------- | +| uuid | string | UUID of the requested user | +| username | string | Username of the requested user | +| display_name | string | Display Name of the requested user | + +```json +{ + "uuid": "7292d678-e718-4dbc-b2d5-e42a22abfdd6", + "username": "radial_4740", + "display_name": "Radial" +} +``` + +--- + +### 500 + +| Name | Type | Description | +| ----- | ------ | -------------------------------- | +| error | string | The error the server encountered | + +```json +{ + "error": "Something went wrong!", +} +``` From 78970bf292df1a760fc120e10ddfaaee235db818 Mon Sep 17 00:00:00 2001 From: Radical Date: Fri, 2 May 2025 11:55:25 +0200 Subject: [PATCH 4/5] docs: add refresh/revoke endpoints for token handling --- API/client-server/v1/auth/refresh.md | 60 +++++++++++++++++++++++++++ API/client-server/v1/auth/revoke.md | 62 ++++++++++++++++++++++++++++ 2 files changed, 122 insertions(+) create mode 100644 API/client-server/v1/auth/refresh.md create mode 100644 API/client-server/v1/auth/revoke.md diff --git a/API/client-server/v1/auth/refresh.md b/API/client-server/v1/auth/refresh.md new file mode 100644 index 0000000..7e8d8bb --- /dev/null +++ b/API/client-server/v1/auth/refresh.md @@ -0,0 +1,60 @@ +POST /v1/auth/refresh + +--- + +Reauthenticates the user using the refresh token, and issues an access token for future requests. + +--- + +## Request + +| Name | Type | Description | +| ------------- | ------ | --------------------- | +| refresh_token | string | User's refresh token. | + +```json +{ + "refresh_token": "aeb343482fcee3a293e887f5dc840ea8b0fc6b54a26c2584a95a5bc91ff4a749", +} +``` + +--- + +## Responses + +| Status | Description | +|--------|-------------------------------------------------| +| 200 | Authentication successful. | +| 400 | The post request included poorly formated data. | +| 403 | Part of the cridentials are invalid. | +| 500 | An unhandled error occured. | + +--- + +### 200 + +| Name | Type | Description | +| ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| access_token | string | **Required**: The access token that will be used for further authentication. | +| refresh_token | string | The refresh token that will be used to refresh the access token. Required for avoiding users having to log in after access token expiration. NOTE: This endpoint returns the same refresh_token if it was generated less than 23 days ago. | + +```json +{ + "access_token": "85b2afece430e0e924f2d4277324c868", + "refresh_token": "aeb343482fcee3a293e887f5dc840ea8b0fc6b54a26c2584a95a5bc91ff4a749" +} +``` + +--- + +### 500 + +| Name | Type | Description | +| ----- | ------ | -------------------------------- | +| error | string | The error the server encountered | + +```json +{ + "error": "Something went wrong!", +} +``` diff --git a/API/client-server/v1/auth/revoke.md b/API/client-server/v1/auth/revoke.md new file mode 100644 index 0000000..85c24c4 --- /dev/null +++ b/API/client-server/v1/auth/revoke.md @@ -0,0 +1,62 @@ +POST /v1/auth/revoke + +--- + +Revokes authenticated refresh/access tokens owned by the user. + +--- + +## Request + +| Name | Type | Description | +| ------------ | ------ | ----------------------------------------------------------------------------------------------------------- | +| access_token | string | User's access token to validate the session. | +| password | string | SHA3-384 of user password to ensure its the user trying to do this and not someone who has the access token | +| device_name | string | device_name that should be removed from the list of logins (NOTE: Removes all devices with the same name) | + +```json +{ + "access_token": "85b2afece430e0e924f2d4277324c868", + "password": "f324cbd421326a2abaedf6f395d1a51e189d4a71c755f531289e519f079b224664961e385afcc37da348bd859f34fd1c", + "device_name": "Laptop" +} +``` + +--- + +## Responses + +| Status | Description | +|--------|-------------------------------------------------| +| 200 | Deletion successful. | +| 400 | The post request included poorly formated data. | +| 403 | Part of the cridentials are invalid. | +| 500 | An unhandled error occured. | + +--- + +### 200 + +| Name | Type | Description | +| ------- | ---- | --------------------------------------------------------------------- | +| deleted | bool | Returns true if the refresh/access token(s) were successfully deleted | + +```json +{ + "deleted": true +} +``` + +--- + +### 500 + +| Name | Type | Description | +| ----- | ------ | -------------------------------- | +| error | string | The error the server encountered | + +```json +{ + "error": "Something went wrong!", +} +``` From f70d76390bfa593e34cb6fb3657f131e73c5fa9b Mon Sep 17 00:00:00 2001 From: Radical Date: Fri, 2 May 2025 21:39:03 +0200 Subject: [PATCH 5/5] Revert "docs: add user endpoint from backend" This reverts commit 37309f461b17cee925ff924a6ddd9c58e4eceecc. --- API/client-server/v1/user.md | 64 ------------------------------------ 1 file changed, 64 deletions(-) delete mode 100644 API/client-server/v1/user.md diff --git a/API/client-server/v1/user.md b/API/client-server/v1/user.md deleted file mode 100644 index 4c1d53d..0000000 --- a/API/client-server/v1/user.md +++ /dev/null @@ -1,64 +0,0 @@ -POST /v1/user/me -POST /v1/user/{UUID} - ---- - -Gathers information about the requested user. - ---- - -## Request - -| Name | Type | Description | -| ------------ | ------ | ------------------------------------ | -| access_token | string | **Required**: The user's auth token. | - - -```json -{ - "access_token": "85b2afece430e0e924f2d4277324c868", -} -``` - ---- - -## Responses - -| Status | Description | -| ------ | ----------------------------------------------- | -| 200 | User data found. | -| 400 | The post request included poorly formated data. | -| 403 | Invalid access token. | -| 500 | An unhandled error occured. | - ---- - -### 200 - -| Name | Type | Description | -| ------------ | ------ | ---------------------------------- | -| uuid | string | UUID of the requested user | -| username | string | Username of the requested user | -| display_name | string | Display Name of the requested user | - -```json -{ - "uuid": "7292d678-e718-4dbc-b2d5-e42a22abfdd6", - "username": "radial_4740", - "display_name": "Radial" -} -``` - ---- - -### 500 - -| Name | Type | Description | -| ----- | ------ | -------------------------------- | -| error | string | The error the server encountered | - -```json -{ - "error": "Something went wrong!", -} -```