ErgoAuth: Implementation for Paideia

[noob77777]

ErgoAuth: user authentication protocol between wallet applications and dApps

Contents

• Notes on Paideia Implementation
• ErgoAuth authentication protocol
• Data Formats
• Implementation in Mobile Wallet
• Implementation in dApp

Notes On Paideia Implementaion

• Figure out SigmaBooleans and p2pk addresses
• Websockets - The authentication protocol is async so there needs to be a way for the api to communicate back to the frontend after step 7 of the protocol
• Figure out how to verify the signed message and proof from ErgoAuthResponse #643
• Implementation of SigmaProp and Verify ErgoAuth ergo-python-appkit wrappers
• Implementation in paideia-api

ErgoAuth authentication protocol

An authentication with ErgoAuth is driven by a dApp that needs to authenticate a user.

1. The user enters the necessary information in the dApp's UI for the dApp to know if authentication
   is necessary. For example, users might enter their P2PK address (or, instead of manually entering,
   use ErgoPay to send the address to the dApp automatically).

2. The dApp determines that authenticating the user is needed. For this, the dApp prepares a unique
   message that the wallet app should sign with a user's private key, and a SigmaBoolean that the user
   needs to authenticate for. This might be a P2PK address wrapped in a SigmaBoolean.

3. The dApp presents an ErgoAuth link for the user to click and open the wallet app and a QR code
   for mobile users to scan from within the wallet app.

4. The wallet application parses the QR code/link data and obtains a
   ErgoAuthRequestUrl to fetch the actual ErgoAuthRequest data from
   (see Data Formats section).

5. When ErgoAuthRequest is obtained, the wallet presents a screen showing that a dApp wants to
   authenticate the user, and the address the request is for. The wallet app should also inform the
   user that no funds or moved and no secrets will leave the device.
   In a future enhancement, the Auth Request could be relayed to a Cold wallet device. This is an enhancement
   of EIP-0019 and would not change ErgoAuth protocol.

6. When the user agrees, the wallet app adds some own bytes to the obtained message from ErgoAuthRequest,
   signs it and sends the signed message to the ErgoAuthRequest's replyToUrl.

7. The dApp validates the signed message. When successful, it can proceed with its flow.

Data Formats

Wallet apps should be able to initiate ErgoAuth both by using URI schemes
(clickable links) or QR codes.

ergoauth://<URL>

An URL is provided without the https prefix. http communication is not allowed except for IP addresses
(in order to test within a local network).

Examples:

• ergoauth://sigmavalley.io/auth/2021-16b8-66c4-b800-6e52-8ce4 will make the wallet app request
  https://sigmausd.io/auth/2021-16b8-66c4-b800-6e52-8ce4
• ergoauth://192.168.0.1/auth will make the wallet app request
  http://192.168.0.1/auth

Response body: ErgoAuthRequest

The wallet application should request URL and obtain the following data (json format)

ErgoAuthRequest:
  - signingMessage: String
  - sigmaBoolean: String (base64 from serialized SigmaBoolean)
  - userMessage: String (optional*)
  - messageSeverity: String (optional) "INFORMATION", "WARNING"
  - replyToUrl: String

(Remark: An Ergo p2pk address is a SigmaBoolean, so authenticating a wallet address is possible with this)

If provided, the wallet application should show the userMessage and display the messageSeverity
in a suitable way.

After signing is performed, the
wallet must POST the following data to the dApp using replyToUrl from the
request (json format).

ErgoAuthResponse:
  - signedMessage: String
  - proof: String (Base64)

signedMessage: Message containing the signingMessage sent by the dApp with additional bytes added by the
wallet. The addition of random bytes is done to prevent letting the user signing a message that might be used
for unwanted malicious tasks.

proof: Output of signing signedMessage

In case there was an error building the ErgoAuthRequest on the dApp side, the dApp might reply
with an ErgoAuthRequestError to inform the user about the error:

ErgoAuthRequestError:
  - userMessage: String

The wallet application will show the user message to the user.

Implementation in wallet app

Ergo Wallet App #112

Implementation in dApp

Ergo Appkit #157

dApp: Added to ErgoPay backend example