Merge pull request #228 from Vanessa-Kris/Bridge/Documentation

Resolves #161 
Resolves #162

docs/grpc.md

@@ -13,6 +13,10 @@
     - [Authenticate an Entity](#authenticate-an-entity)
       - [Initiate Authentication](#initiate-authentication)
       - [Complete Authentication](#complete-authentication)
+    - [Create Bridge Entity](#create-bridge-entity)
+      - [Initiate Bridge Creation](#initiate-bridge-creation)
+      - [Complete  Bridge Creation](#complete-bride-creation)
+    - [Authenticate Bridge Entity](#authenticate-bridge-entity)
     - [List an Entity's Stored Tokens](#list-an-entitys-stored-tokens)
     - [Delete An Entity](#delete-an-entity)
     - [Reset an Entity's Password](#reset-an-entitys-password)
@@ -530,6 +534,263 @@ localhost:6000 vault.v1.Entity/AuthenticateEntity <payload.json
 }
 ```
 
+### Create Bridge Entity
+
+An entity represents a user or client in the vault.
+
+---
+
+#### Initiate Bridge Creation
+
+Before creating a bridge entity, you must prove ownership of the phone number you
+intend to use. This step ensures security and authenticity in the entity creation process.
+
+---
+
+##### Request
+
+> `request` **CreateBridgeEntityRequest**
+
+> [!IMPORTANT]
+>
+> The table lists only the required fields for this step. Other fields will be
+> ignored.
+
+| Field                  | Type   | Description                                                                                                                                |
+|------------------------|--------|--------------------------------------------------------------------------------------------------------------------------------------------|
+| phone_number          | string | The phone number associated with the bridge entity. It should be in [E164 format](https://en.wikipedia.org/wiki/E.164), e.g., +237123456789. |
+| country_code          | string | The [ISO 3166-1 alpha-2 code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) associated with the phone number. e.g., `CM` for Cameroon. |
+| client_publish_pub_key | string | An `X25519` public key for publishing, `base64 encoded`.                                                                                   |
+
+                               
+---
+
+##### Response
+
+> `response` **CreateBridgeEntityResponse**
+
+> [!IMPORTANT]
+>
+> The table lists only the fields that are populated for this step. Other fields
+> may be empty, omitted, or false.
+
+| Field                   | Type  | Description                                                       |
+|-------------------------|-------|-------------------------------------------------------------------|
+| message                | string | A response message from the server.                              |
+| success                | bool   | Indicates whether the operation was successful. `true` or `false`. |
+
+---
+
+##### Method
+
+> `method` **CreateBridgeEntity**
+
+> [!TIP]
+>
+> The examples below use [grpcurl](https://github.com/fullstorydev/grpcurl#grpcurl).
+
+> [!NOTE]
+>
+> Here is what a successful response from the server looks like.
+>
+> The server would return a status code of `0 OK` if the API transaction goes
+> through without any friction. Otherwise, it will return any other code out of
+> the [17 codes supported by gRPC](https://grpc.github.io/grpc/core/md_doc_statuscodes.html).
+
+---
+
+**Sample request**
+
+```bash
+grpcurl -plaintext \
+    -d @ \
+    -proto protos/v1/vault.proto \
+localhost:6000 vault.v1.Entity/CreateBridgeEntity <payload.json
+```
+
+---
+
+**Sample payload.json**
+
+```json
+{
+  "country_code": "CM",
+  "phone_number": "+237123456789",
+  "client_publish_pub_key": "x25519 client publish public key"
+}
+```
+
+---
+
+**Sample response**
+
+```json
+{
+  "success": true,
+  "message": "Bridge entity created successfully."
+}
+```
+
+---
+
+#### Complete Bridge Creation
+
+> [!WARNING]
+>
+> Ensure that you have completed the [Initiate Bridge Creation](#initiate-bridge-creation)
+> step before executing this step.
+
+---
+
+##### Request
+
+> `request` **CreateBridgeEntityRequest**
+
+> [!IMPORTANT]
+>
+> The table lists only the required fields for this step. Other fields will be
+> ignored.
+
+| Field                    | Type   | Description                                                                                                                                |
+|--------------------------|--------|--------------------------------------------------------------------------------------------------------------------------------------------|
+| phone_number            | string | The phone number associated with the bridge entity. It should be in [E164 format](https://en.wikipedia.org/wiki/E.164), e.g., +237123456789. |
+| country_code            | string | The [ISO 3166-1 alpha-2 code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) associated with the phone number. e.g., `CM` for Cameroon. |
+| ownership_proof_response | string | The proof response from the previous step.                                                                                                |
+
+---
+
+##### Response
+
+> `response` **CreateBridgeEntityResponse**
+
+> [!IMPORTANT]
+>
+> The table lists only the fields that are populated for this step. Other fields
+> may be empty, omitted, or false.
+
+| Field                   | Type  | Description                                                       |
+|-------------------------|-------|-------------------------------------------------------------------|
+| message                | string | A response message from the server.                              |
+| success                | bool   | Indicates whether the operation was successful. `true` or `false`. |
+
+---
+
+##### Method
+
+> `method` **CreateBridgeEntity**
+
+> [!TIP]
+>
+> The examples below use [grpcurl](https://github.com/fullstorydev/grpcurl#grpcurl).
+
+> [!NOTE]
+>
+> Here is what a successful response from the server looks like.
+>
+> The server would return a status code of `0 OK` if the API transaction goes
+> through without any friction. Otherwise, it will return any other code out of
+> the [17 codes supported by gRPC](https://grpc.github.io/grpc/core/md_doc_statuscodes.html).
+
+---
+
+**Sample request**
+
+```bash
+grpcurl -plaintext \
+    -d @ \
+    -proto protos/v1/vault.proto \
+localhost:6000 vault.v1.Entity/CreateBridgeEntity <payload.json
+```
+
+---
+
+**Sample payload.json**
+
+```json
+{
+  "country_code": "CM",
+  "phone_number": "+237123456789",
+  "ownership_proof_response": "123456"
+}
+```
+
+---
+
+**Sample response**
+
+```json
+{
+  "success": true,
+  "message": "Bridge entity creation completed successfully."
+}
+```
+
+---
+
+### Authenticate Bridge Entity
+
+An entity represents a user or client in the vault.
+
+---
+
+##### Request
+
+> `request` **AuthenticateBridgeEntityRequest**
+
+| Field         | Type   | Description                                        |
+| ------------- | ------ | -------------------------------------------------- |
+| phone_number  | string | The phone number associated with the bridge entity. |
+
+---
+
+##### Response
+
+> `response` **AuthenticateBridgeEntityResponse**
+
+| Field   | Type   | Description                                  |
+| ------- | ------ | -------------------------------------------- |
+| message | string | A response message from the server.          |
+| success | bool   | Indicates whether authentication was successful. |
+
+---
+
+##### Method
+
+> `method` **AuthenticateBridgeEntity**
+
+---
+
+**Sample request**
+
+```bash
+grpcurl -plaintext \
+    -d @ \
+    -proto protos/v1/vault.proto \
+localhost:6000 vault.v1.Entity/AuthenticateBridgeEntity <payload.json
+```
+
+---
+
+**Sample payload.json**
+
+```json
+{
+  "phone_number": "+237123456789"
+}
+```
+
+---
+
+**Sample response**
+
+```json
+{
+  "success": true,
+  "message": "Bridge entity authenticated successfully."
+}
+```
+
+
 ### List an Entity's Stored Tokens
 
 This method retrieves the stored tokens for a given entity.