From 4e0c4b1d115118d1c5024697b806d1e169b038dd Mon Sep 17 00:00:00 2001 From: ChronosX88 Date: Mon, 16 Dec 2019 17:14:18 +0400 Subject: [PATCH 01/10] Correct Protocol Errors extension - add ok variable --- protocol-spec/json-schema/BaseMessage.schema.json | 6 ++++++ protocol-spec/protocol-errors.md | 5 +++-- 2 files changed, 9 insertions(+), 2 deletions(-) diff --git a/protocol-spec/json-schema/BaseMessage.schema.json b/protocol-spec/json-schema/BaseMessage.schema.json index 30ce414..343b1db 100644 --- a/protocol-spec/json-schema/BaseMessage.schema.json +++ b/protocol-spec/json-schema/BaseMessage.schema.json @@ -62,6 +62,12 @@ "type": "object", "title": "payload", "description": "Message payload (used to store extra information in message, list of permissible fields in the payload depends on \"type\" field)" + }, + "ok": { + "$id": "#/properties/ok", + "type": "boolean", + "title": "ok", + "description": "Indicating whether request have an error" } } } diff --git a/protocol-spec/protocol-errors.md b/protocol-spec/protocol-errors.md index a9c52c3..159e18f 100644 --- a/protocol-spec/protocol-errors.md +++ b/protocol-spec/protocol-errors.md @@ -1,7 +1,7 @@ # Protocol Errors ## Introduction Mechanism of error processing included into protocol. -Adds into any type ID `:error` postfix. +Adds into any response message `ok` variable. If `ok` is true - we have no errors, if `ok` is false - we have an error. ## Message type identifiers - `*:error` @@ -24,9 +24,10 @@ Adds into any type ID `:error` postfix. ```json { "id": "abcd", - "type": "incorrectMessageType:error", + "type": "incorrectMessageType", "from": "cadmium.im", "to": "@juliet@cadmium.im", + "ok": false, "payload": { "errCode": 0, "errText": "Incorrect type of message (type isn't implemented in the server)", From 50807e52c0fd718ebc72be2d56beb9ddf9beefd8 Mon Sep 17 00:00:00 2001 From: ChronosX88 Date: Mon, 16 Dec 2019 17:53:37 +0400 Subject: [PATCH 02/10] Lint Account Registration --- protocol-spec/account-registration.md | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/protocol-spec/account-registration.md b/protocol-spec/account-registration.md index 7daf529..9f1cce5 100644 --- a/protocol-spec/account-registration.md +++ b/protocol-spec/account-registration.md @@ -1,17 +1,23 @@ # Account registration + ## Introduction + This extension is intended for creating user accounts on a server ## Message type identifiers -- `profile:register` + +- `profile:register` ## Error codes + - 0: limit exceed - 1: username/third party ID already taken - 2: registration isn't allowed on a server ## Use cases + - Request: + ```json { "id": "abcd", @@ -29,6 +35,7 @@ This extension is intended for creating user accounts on a server ``` - Response: + ```json { "id": "abcd", @@ -56,12 +63,15 @@ This extension is intended for creating user accounts on a server ``` ## Business Rules + None. ## JSON Schema -**Payload** + +### Payload - Request: + ```typescript interface RegistrationRequestPayload { /** @@ -92,7 +102,9 @@ interface ThirdPartyID { value: string } ``` + - Response: + ```typescript interface RegistrationResponsePayload { /** @@ -100,4 +112,4 @@ interface RegistrationResponsePayload { */ userID: EntityID } -``` \ No newline at end of file +``` From 89e14cbcee02ed18e8500ec0ca5105b92469acd4 Mon Sep 17 00:00:00 2001 From: ChronosX88 Date: Sun, 22 Dec 2019 18:39:30 +0400 Subject: [PATCH 03/10] Lint all MDs files --- protocol-spec/account-login-by-username.md | 21 +++++++++-- protocol-spec/account-registration.md | 3 +- .../cadmium-extension-document-format.md | 36 +++++++++++++++---- protocol-spec/core.md | 24 ++++++++----- protocol-spec/protocol-errors.md | 13 +++++-- 5 files changed, 74 insertions(+), 23 deletions(-) diff --git a/protocol-spec/account-login-by-username.md b/protocol-spec/account-login-by-username.md index 1fd024a..839b651 100644 --- a/protocol-spec/account-login-by-username.md +++ b/protocol-spec/account-login-by-username.md @@ -1,16 +1,22 @@ # Account login by username + ## Introduction + This extension is intended for logging into user account on a server by username ## Message type identifiers + - `profile:login` ## Error codes + - 0: limit exceed - 1: user ID/password isn't valid ## Use cases + *Request*: + ```json { "id": "abcd", @@ -24,6 +30,7 @@ This extension is intended for logging into user account on a server by username ``` *Response*: + ```json { "id": "abcd", @@ -38,6 +45,7 @@ This extension is intended for logging into user account on a server by username ``` *Error response*: + ```json { "id": "abcd", @@ -52,33 +60,40 @@ This extension is intended for logging into user account on a server by username ``` ## Business Rules + None. ## JSON Schema -**Payload** + +### Payload - Request: + ```typescript interface LoginRequestPayload { /** * The username of account which user wants to login */ username: string, - + + /** * Password of new account */ password: string } ``` + - Response: + ```typescript interface LoginResponsePayload { /** * Authentication token which required for various user actions (UUID) */ authToken: string, - + + /** * Identifier of new user device (created by this login action) */ diff --git a/protocol-spec/account-registration.md b/protocol-spec/account-registration.md index 9f1cce5..195a342 100644 --- a/protocol-spec/account-registration.md +++ b/protocol-spec/account-registration.md @@ -48,7 +48,8 @@ This extension is intended for creating user accounts on a server } ``` -*Error response*: +- Error response: + ```json { "id": "abcd", diff --git a/protocol-spec/cadmium-extension-document-format.md b/protocol-spec/cadmium-extension-document-format.md index 177185d..51276f3 100644 --- a/protocol-spec/cadmium-extension-document-format.md +++ b/protocol-spec/cadmium-extension-document-format.md @@ -1,14 +1,19 @@ # The Sections of a Cadmium Extension (CE) document + ## Introduction + The introduction to a CE document should contain description of the extension and example of problems which this extension can solve. ## Message type identifiers + In this section, specify the identifiers of the new types of protocol messages (which are introduced by the extension) ## Glossary + If your CE document uses terms that may not be familiar to the reader, please define them in this section. ## Use Cases + It is recommended that document authors structure their proposals according to the use cases that the proposal will address. We have found that use cases force authors to focus on functionality rather than "protocol for the sake of protocol". It is also helpful to sort use cases by actor. Include one subsection for each use case. When writing use cases and the associated protocols, make sure to: @@ -18,6 +23,7 @@ When writing use cases and the associated protocols, make sure to: * Include lots of protocol examples. *Example 1. An Example from Shakespeare* + ```json { "id": "abcd", @@ -29,31 +35,41 @@ When writing use cases and the associated protocols, make sure to: } } ``` + ## Error Codes + If your proposal defines a number of error and status codes, it is a good idea to include a table of all the codes defined in your document. ## Business Rules + You may want to include a section describing various business rules (essentially, a variety of MUSTs, SHOULDs, and MAYs regarding application behavior). This is not required but can be helpful to implementers. ## Implementation Notes + You may want to include a section devoted to implementation notes. Again, this is not required but can be helpful to implementers. ## Internationalization Considerations + If there are any internationalization or localization issues related to your proposal, define them in this optional section. ## Security Considerations + Your proposal MUST include a section entitled "Security Considerations". Even if there are no security features or concerns related to your proposal, you MUST note that fact. For helpful guidelines, refer to RFC 3552. ## JSON Schema + An JSON Schema is required in order for protocols to be approved by the Cadmium Developers. The Cadmium Developers team can assist you in defining an JSON Schema for the protocol you are proposing. Also you can define your schema as TypeScript interfaces, this is also allowed. ## Acknowledgements (optional) + Most CE documents end with a section thanking non-authors who have made significant contributions or who have provided feedback regarding the specification. -# Cadmium Extension Styleguide +## Cadmium Extension Styleguide + CE document are written in English. It is not expected that you will be a fine prose writer, but try to write in a clear, easily-understood fashion. -## Code Examples +### Code Examples + To show the hierarchy of JSON objects, indent two spaces for every level. If an element possesses a large number of attributes, include a line break before each attribute and indent them so that they are vertically aligned for readability. @@ -61,6 +77,7 @@ If an element possesses a large number of attributes, include a line break befor If the JSON data of an element is long, include line breaks and indent by two spaces. *Example*: + ```json { "id": "abcd", @@ -76,14 +93,19 @@ If the JSON data of an element is long, include line breaks and indent by two sp } } ``` + Some examples include strings that are the output of a hashing algorithm such as SHA-1 or SHA-256. An easy way to generate these is to use the OpenSSL "dgst" command to generate the hash. For example, the following command will generate the SHA-1 hash `a6cf4baabcefb63189a1a1c56158aa431990bba9`: -``` + +```bash echo -n '@juliet@396277b7dcd0f1173f2007baa604de7593529cc3fbf335fb7924851cb25c1fdf' | openssl dgst -hex -sha1 ``` - + Some examples include strings that are encoded using Base64. An easy way to generate these is to use the OpenSSL "enc" command to generate the base64-encoded equivalent. For example, the following command will generate the base64-encoded string `QGp1bGlldEAzOTYyNzdiN2RjZDBmMTE3M2YyMDA3YmFhNjA0ZGU3NTkzNTI5Y2MzZmJmMzM1ZmI3OTI0ODUxY2IyNWMxZmRm`: -``` + +```bash echo -n '@juliet@396277b7dcd0f1173f2007baa604de7593529cc3fbf335fb7924851cb25c1fdf' | openssl enc -nopad -base64 -``` -## Conformance Terms +``` + +### Conformance Terms + Conformance terms (e.g,, "MUST" and "SHOULD") are specified in RFC 2119. Use them. When such terms are not in ALL CAPS, the special conformance sense does not apply (although it is preferable to use terms such as 'might' instead of 'may' and 'ought' instead of 'should'). \ No newline at end of file diff --git a/protocol-spec/core.md b/protocol-spec/core.md index ea7dd8b..d3f7165 100644 --- a/protocol-spec/core.md +++ b/protocol-spec/core.md @@ -6,32 +6,38 @@ - [BaseMessage](#basemessage) ## Transport + For starting we simply use JSON + Websockets. ## Entity ID -* Room alias: `#@` -* Username: `@@` -* User ID with any 3PID: `%:@` - * Currently supported only following types: `email` and `msisdn`. -* Raw User ID: `@@` -* Message ID: `&@` -* Room ID: `!@` -* Single server-part: `` + +- Room alias: `#@` +- Username: `@@` +- User ID with any 3PID: `%:@` + - Currently supported only following types: `email` and `msisdn`. +- Raw User ID: `@@` +- Message ID: `&@` +- Room ID: `!@` +- Single server-part: `` **Server-part**: + - hostname: `IPv4 / [IPv6] / dns-domain:` (for end-users use) - server ID: static SHA256 hash string from 4096 characters (for internal protocol use) **Username/Room alias/RoomID** - MUST NOT be empty, and MUST contain only the characters `a-z`, `0-9`, `.`, `_`, `=`, `-`, and `/`. **Special business rules**: + - RoomID SHOULD be UUID identifier. - Servers MUST use server ID in internal purposes instead of normal server-part with hostname. Only end-users MUST use normal server-part with hostname. This is done for easy multi-domain serving. ## BaseMessage + BaseMessage is a basic message model, basis of the whole protocol. It is used for a very easy protocol extension process. BaseMessage scheme: + ```typescript interface BaseMessage { /** @@ -63,4 +69,4 @@ interface BaseMessage { */ payload: Map } -``` \ No newline at end of file +``` diff --git a/protocol-spec/protocol-errors.md b/protocol-spec/protocol-errors.md index 159e18f..28e28cf 100644 --- a/protocol-spec/protocol-errors.md +++ b/protocol-spec/protocol-errors.md @@ -1,13 +1,18 @@ # Protocol Errors + ## Introduction + Mechanism of error processing included into protocol. Adds into any response message `ok` variable. If `ok` is true - we have no errors, if `ok` is false - we have an error. ## Message type identifiers -- `*:error` + +None. ## Use cases + *Request*: + ```json { "id": "abcd", @@ -21,6 +26,7 @@ Adds into any response message `ok` variable. If `ok` is true - we have no error ``` *Response*: + ```json { "id": "abcd", @@ -37,7 +43,8 @@ Adds into any response message `ok` variable. If `ok` is true - we have no error ``` ## JSON Schema -**Payload** + +### Payload ```typescript interface ErrorPayload { @@ -56,4 +63,4 @@ interface ErrorPayload { */ errPayload: Map } -``` \ No newline at end of file +``` From d548097e32e976cf0c5dac8979823d5687c39684 Mon Sep 17 00:00:00 2001 From: ChronosX88 Date: Thu, 26 Dec 2019 17:39:16 +0400 Subject: [PATCH 04/10] Change error code to error identifier in Protocol Errors extension --- protocol-spec/protocol-errors.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/protocol-spec/protocol-errors.md b/protocol-spec/protocol-errors.md index 28e28cf..116a24e 100644 --- a/protocol-spec/protocol-errors.md +++ b/protocol-spec/protocol-errors.md @@ -49,9 +49,9 @@ None. ```typescript interface ErrorPayload { /** - * Error code (defined in extensions, may be same per extensions) + * Error identifier (defined in extensions, maybe same per extensions) */ - errCode: number, + errId: string, /** * Explanation of error in human-readable view From f209420ee003355f215ef79997d3c3297254f196 Mon Sep 17 00:00:00 2001 From: ChronosX88 Date: Thu, 26 Dec 2019 17:39:50 +0400 Subject: [PATCH 05/10] Fix login/registration extensions --- protocol-spec/account-login-by-username.md | 9 ++++----- protocol-spec/account-registration.md | 19 ++++++++++--------- 2 files changed, 14 insertions(+), 14 deletions(-) diff --git a/protocol-spec/account-login-by-username.md b/protocol-spec/account-login-by-username.md index 839b651..27c69bf 100644 --- a/protocol-spec/account-login-by-username.md +++ b/protocol-spec/account-login-by-username.md @@ -8,10 +8,9 @@ This extension is intended for logging into user account on a server by username - `profile:login` -## Error codes +## Error Identifiers -- 0: limit exceed -- 1: user ID/password isn't valid +- `invalid_creds`: user ID/password isn't valid ## Use cases @@ -53,7 +52,7 @@ This extension is intended for logging into user account on a server by username "from": "cadmium.org", "ok": false, "payload": { - "errCode": 1, + "errCode": "invalid_creds", "errText": "Username/password isn't valid" } } @@ -61,7 +60,7 @@ This extension is intended for logging into user account on a server by username ## Business Rules -None. +- Ratelimit system: enabled ## JSON Schema diff --git a/protocol-spec/account-registration.md b/protocol-spec/account-registration.md index 195a342..570d946 100644 --- a/protocol-spec/account-registration.md +++ b/protocol-spec/account-registration.md @@ -8,15 +8,16 @@ This extension is intended for creating user accounts on a server - `profile:register` -## Error codes +## Error identifiers -- 0: limit exceed -- 1: username/third party ID already taken -- 2: registration isn't allowed on a server +- `id_exists`: username/third party ID already taken +- `reg_disabled`: registration isn't allowed on a server ## Use cases -- Request: +### Basic registration flow (with CAPTCHA) + +- Client: ```json { @@ -34,7 +35,7 @@ This extension is intended for creating user accounts on a server } ``` -- Response: +- Server: ```json { @@ -57,15 +58,15 @@ This extension is intended for creating user accounts on a server "from": "cadmium.org", "ok": false, "payload": { - "errCode": 1, - "errText": "{Username/email/msisdn} already taken" + "errCode": "id_exists", + "errText": "Username/email/msisdn already taken" } } ``` ## Business Rules -None. +- Ratelimit system: enabled ## JSON Schema From 0688f8849d283dc5e1fa7c03d01ec97395b61e29 Mon Sep 17 00:00:00 2001 From: ChronosX88 Date: Thu, 26 Dec 2019 17:41:23 +0400 Subject: [PATCH 06/10] Fix CEDF --- protocol-spec/account-login-by-username.md | 5 +++-- protocol-spec/account-registration.md | 3 ++- protocol-spec/cadmium-extension-document-format.md | 8 ++++---- 3 files changed, 9 insertions(+), 7 deletions(-) diff --git a/protocol-spec/account-login-by-username.md b/protocol-spec/account-login-by-username.md index 27c69bf..cec0e6d 100644 --- a/protocol-spec/account-login-by-username.md +++ b/protocol-spec/account-login-by-username.md @@ -8,8 +8,9 @@ This extension is intended for logging into user account on a server by username - `profile:login` -## Error Identifiers +## Errors +- Ratelimit system: enabled - `invalid_creds`: user ID/password isn't valid ## Use cases @@ -60,7 +61,7 @@ This extension is intended for logging into user account on a server by username ## Business Rules -- Ratelimit system: enabled +None. ## JSON Schema diff --git a/protocol-spec/account-registration.md b/protocol-spec/account-registration.md index 570d946..9224723 100644 --- a/protocol-spec/account-registration.md +++ b/protocol-spec/account-registration.md @@ -10,6 +10,7 @@ This extension is intended for creating user accounts on a server ## Error identifiers +- Ratelimit system: enabled - `id_exists`: username/third party ID already taken - `reg_disabled`: registration isn't allowed on a server @@ -66,7 +67,7 @@ This extension is intended for creating user accounts on a server ## Business Rules -- Ratelimit system: enabled +None. ## JSON Schema diff --git a/protocol-spec/cadmium-extension-document-format.md b/protocol-spec/cadmium-extension-document-format.md index 51276f3..98d9dd6 100644 --- a/protocol-spec/cadmium-extension-document-format.md +++ b/protocol-spec/cadmium-extension-document-format.md @@ -22,7 +22,7 @@ When writing use cases and the associated protocols, make sure to: * Describe the expected behavior of Cadmium clients, servers, and components when using this protocol. * Include lots of protocol examples. -*Example 1. An Example from Shakespeare* +*Example 1. An Example from Shakespeare*: ```json { @@ -36,13 +36,13 @@ When writing use cases and the associated protocols, make sure to: } ``` -## Error Codes +## Errors -If your proposal defines a number of error and status codes, it is a good idea to include a table of all the codes defined in your document. +If your proposal defines a number of error and error identifiers, it is a good idea to include a table of all the identifiers defined in your document. ## Business Rules -You may want to include a section describing various business rules (essentially, a variety of MUSTs, SHOULDs, and MAYs regarding application behavior). This is not required but can be helpful to implementers. +You may want to include a section describing various business rules (essentially, a variety of MUSTs, SHOULDs, and MAYs regarding application behavior). This section is not required but can be helpful to implementers. ## Implementation Notes From 78250add03e2de06014a62d9954e7eb4db632382 Mon Sep 17 00:00:00 2001 From: ChronosX88 Date: Thu, 26 Dec 2019 17:41:38 +0400 Subject: [PATCH 07/10] Describe basic request ratelimit system --- protocol-spec/basic-request-ratelimit.md | 68 ++++++++++++++++++++++++ 1 file changed, 68 insertions(+) create mode 100644 protocol-spec/basic-request-ratelimit.md diff --git a/protocol-spec/basic-request-ratelimit.md b/protocol-spec/basic-request-ratelimit.md new file mode 100644 index 0000000..360e171 --- /dev/null +++ b/protocol-spec/basic-request-ratelimit.md @@ -0,0 +1,68 @@ +# Basic request ratelimit system + +## Introduction + +This extension is intended to limit the number of requests from clients per unit of time. It is based on Protocol Errors extension. + +## Message type identifiers + +None. + +## Use cases + +- Client: + +```json +{ + "id": "abcd", + "type": "profile:register", + "to": "cadmium.org", + "payload": { + "username": "spam_spam_spam", + "thirdPIDs": [], + "password": "spam" + } +} +``` + +- Server: + +```json +{ + "id": "abcd", + "type": "profile:register", + "from": "cadmium.org", + "ok": false, + "payload": { + "errCode": "ratelimit_exceed", + "errText": "Request ratelimit exceed! Please, try again later!", + "errPayload": { + "retryAfter": 2 + } + } +} +``` + +## Error Identifiers + +### Global error identifiers + +- `ratelimit_exceed` + +## Business Rules + +- Server MUST count number of requests per unit of time and drop new requests after specified number of made requests with Protocol Error message. +- Number of requests and used unit of time SHOULD be configurable on server + +## JSON Schema + +### Error payload + +```typescript +interface RatelimitExceedErrorPayload { + /** + * How long after the client can retry the request (in seconds) + */ + retryAfter: number +} +``` From ddef4e794b241c56a02cfa32d8a05cd7318b9951 Mon Sep 17 00:00:00 2001 From: ChronosX88 Date: Thu, 26 Dec 2019 18:39:19 +0400 Subject: [PATCH 08/10] Update Account Registration and Basic Request Ratelimit --- protocol-spec/account-registration.md | 2 +- protocol-spec/basic-request-ratelimit.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/protocol-spec/account-registration.md b/protocol-spec/account-registration.md index 9224723..f2d8dd3 100644 --- a/protocol-spec/account-registration.md +++ b/protocol-spec/account-registration.md @@ -8,7 +8,7 @@ This extension is intended for creating user accounts on a server - `profile:register` -## Error identifiers +## Errors - Ratelimit system: enabled - `id_exists`: username/third party ID already taken diff --git a/protocol-spec/basic-request-ratelimit.md b/protocol-spec/basic-request-ratelimit.md index 360e171..840c5d6 100644 --- a/protocol-spec/basic-request-ratelimit.md +++ b/protocol-spec/basic-request-ratelimit.md @@ -43,9 +43,9 @@ None. } ``` -## Error Identifiers +## Errors -### Global error identifiers +### Global errors - `ratelimit_exceed` From 7474e63fd3f917b66ef38763bc7891d8df2f400e Mon Sep 17 00:00:00 2001 From: ChronosX88 Date: Sun, 29 Dec 2019 17:01:35 +0400 Subject: [PATCH 09/10] Update --- protocol-spec/account-login-by-username.md | 4 ++-- protocol-spec/account-registration.md | 18 ++++++++++++++---- protocol-spec/core.md | 22 ++++++++++++++++------ 3 files changed, 32 insertions(+), 12 deletions(-) diff --git a/protocol-spec/account-login-by-username.md b/protocol-spec/account-login-by-username.md index cec0e6d..8874e4d 100644 --- a/protocol-spec/account-login-by-username.md +++ b/protocol-spec/account-login-by-username.md @@ -89,7 +89,7 @@ interface LoginRequestPayload { ```typescript interface LoginResponsePayload { /** - * Authentication token which required for various user actions (UUID) + * Authentication token which required for various user actions (static SHA256 hash string from 4096 random characters) */ authToken: string, @@ -99,4 +99,4 @@ interface LoginResponsePayload { */ deviceID: string } -``` \ No newline at end of file +``` diff --git a/protocol-spec/account-registration.md b/protocol-spec/account-registration.md index f2d8dd3..2e981ea 100644 --- a/protocol-spec/account-registration.md +++ b/protocol-spec/account-registration.md @@ -16,7 +16,7 @@ This extension is intended for creating user accounts on a server ## Use cases -### Basic registration flow (with CAPTCHA) +### Basic registration flow - Client: @@ -80,7 +80,7 @@ interface RegistrationRequestPayload { /** * The username that the user wants to register */ - username: string, + username?: string, /** * Array of user third party IDs (email and/or MSISDN) @@ -90,7 +90,12 @@ interface RegistrationRequestPayload { /** * Password of new account */ - password: string + password: string, + + /** + * Login to freshly created user account when registration will be completed + */ + loginOnSuccess: boolean } interface ThirdPartyID { @@ -113,6 +118,11 @@ interface RegistrationResponsePayload { /** * ID of user (Username in priority. If we haven't username, then we put to this field one of user's third party IDs) */ - userID: EntityID + userID: EntityID, + + /** + * Property with login payload (can be omit if property loginOnSuccess wasn't indicated true in RegistrationRequestPayload) + */ + loginPayload?: LoginResponsePayload } ``` diff --git a/protocol-spec/core.md b/protocol-spec/core.md index d3f7165..3cadefb 100644 --- a/protocol-spec/core.md +++ b/protocol-spec/core.md @@ -3,6 +3,9 @@ - [Protocol Core](#protocol-core) - [Transport](#transport) - [Entity ID](#entity-id) + - [Server-part](#server-part) + - [Username/Room alias/RoomID](#usernameroom-aliasroomid) + - [Special business rules](#special-business-rules) - [BaseMessage](#basemessage) ## Transport @@ -16,18 +19,20 @@ For starting we simply use JSON + Websockets. - User ID with any 3PID: `%:@` - Currently supported only following types: `email` and `msisdn`. - Raw User ID: `@@` -- Message ID: `&@` +- Message ID: `&@` - Room ID: `!@` - Single server-part: `` -**Server-part**: +### Server-part - hostname: `IPv4 / [IPv6] / dns-domain:` (for end-users use) -- server ID: static SHA256 hash string from 4096 characters (for internal protocol use) +- server ID: static SHA256 hash string from 4096 characters (for internal protocol use) -**Username/Room alias/RoomID** - MUST NOT be empty, and MUST contain only the characters `a-z`, `0-9`, `.`, `_`, `=`, `-`, and `/`. +### Username/Room alias/RoomID -**Special business rules**: +MUST NOT be empty, and MUST contain only the characters `a-z`, `0-9`, `.`, `_`, `=`, `-`, and `/`. + +### Special business rules - RoomID SHOULD be UUID identifier. - Servers MUST use server ID in internal purposes instead of normal server-part with hostname. Only end-users MUST use normal server-part with hostname. This is done for easy multi-domain serving. @@ -60,10 +65,15 @@ interface BaseMessage { to: EntityID, /** - * Operation success indicator (used to determine if the error happened while processing request) + * Operation success indicator (used to determine if the error happened while processing request) - MUST be only in response from server */ ok: boolean, + /** + * Authentication token string (can be omit if the action does not require user authentication) - MUST be only in request messages from client + */ + authToken?: string, + /** * Message payload (used to store extra information in message, list of permissible fields in the payload depends on "type" field) */ From f55dbf9967f282168dcafc563b92b04191261019 Mon Sep 17 00:00:00 2001 From: ChronosX88 Date: Sun, 29 Dec 2019 18:40:17 +0400 Subject: [PATCH 10/10] Some update --- protocol-spec/account-login-by-username.md | 12 ++++++++---- protocol-spec/account-registration.md | 5 ++++- 2 files changed, 12 insertions(+), 5 deletions(-) diff --git a/protocol-spec/account-login-by-username.md b/protocol-spec/account-login-by-username.md index 8874e4d..cd6f0d1 100644 --- a/protocol-spec/account-login-by-username.md +++ b/protocol-spec/account-login-by-username.md @@ -15,7 +15,7 @@ This extension is intended for logging into user account on a server by username ## Use cases -*Request*: +- Request: ```json { @@ -29,7 +29,7 @@ This extension is intended for logging into user account on a server by username } ``` -*Response*: +- Response: ```json { @@ -44,7 +44,7 @@ This extension is intended for logging into user account on a server by username } ``` -*Error response*: +- Error response: ```json { @@ -72,10 +72,14 @@ None. ```typescript interface LoginRequestPayload { /** - * The username of account which user wants to login + * The username of account which user wants to login (can be omit if we set thirdPID) */ username: string, + /** + * Third party ID which have user (can be omit if we set username) + */ + thirdPID: string, /** * Password of new account diff --git a/protocol-spec/account-registration.md b/protocol-spec/account-registration.md index 2e981ea..4992d1e 100644 --- a/protocol-spec/account-registration.md +++ b/protocol-spec/account-registration.md @@ -18,6 +18,8 @@ This extension is intended for creating user accounts on a server ### Basic registration flow +`// TODO: introduce email/msisdn confirmation which prevents spam attacks` + - Client: ```json @@ -31,7 +33,8 @@ This extension is intended for creating user accounts on a server {"type":"email", "value":"juliet@capulett.com"}, {"type":"msisdn", "value":"+1234567890"}, ], - "password": "romeo1" + "password": "romeo1", + "loginOnSuccess": false } } ```