EIP-0028 ErgoAuth

eip-0028.md

@@ -0,0 +1,130 @@
+# ErgoAuth: user authentication protocol between wallet applications and dApps
+
+* Author: @MrStahlfelge
+* Status: Proposed
+* Created: 25-Jan-2022
+* License: CC0
+* Forking: not needed
+
+## Contents
+- [Description](#description)
+- [Background And Motivation](#background-and-motivation)
+- [ErgoPay Interaction Protocol](#ergoauth-authentication-protocol)
+- [Data Formats](#data-formats)
+- [Implementation in Mobile Wallet](#implementation-in-mobile-wallet)
+- [Implementation in dApp](#implementation-in-dapp)
+- [Benefits for dApps](#benefits-for-dapps)
+- [Benefits for Mobile Wallets](#benefits-for-mobile-wallets)
+
+## Description
+This EIP defines a standard for trustless authentication of users of a wallet app and an online
+dApp.
+
+## Background And Motivation
+
+dApps might want to validate if dApp users are really who they pretend to be. This is especially
+useful for dApps that grant certain abilities to holders of special tokens. At the moment,
+proofing that a user owns a token can only be done by sending the token to a depositary address.
+By sending the token, the user proofed to have access privileges to the token.
+However, sending token around is not always desirable. Especially for valuable tokens, users might
+not want to send it away, and doing two transactions (one to send it to the depositary address, one
+to refund it back) costs both time and transaction fees.
+
+To overcome this, ErgoAuth proposes a way to authenticate users trustless to have access to certain
+addresses storing a box. The protocol is trustless in both ways: The users don't need to trust
+the dApp, because the dApp does not get access to funds or secrets. The dApp don't need to trust
+the users or the wallet app, because it can validate the authentication keys.
+
+## 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 an Ergo address that the user
+needs to authenticate for. This might be a P2PK address, but in general P2S addresses can be also
+used for authentication.
+
+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](#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.
+
+6) When the user agrees, the wallet app signs the obtained message from ErgoAuthRequest 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
+  - address: String
+  - userMessage: String (optional*)
+  - messageSeverity: String (optional) "INFORMATION", "WARNING"
+  - replyToUrl: String
+```
+
+If provided, the wallet application should show the **userMessage** and display the **messageSeverity**
+in a suitable way.
+
+After signing is performed and the `SignedMessage` data is obtained, the
+wallet must POST the following data to the dApp using **replyToUrl** from the
+request (json format).
+
+```
+ErgoAuthResponse:
+  - signedMessage: String (base64)
+```
+
+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
+TODO
+
+## Implementation in dApp
+TODO
+
+## Benefits for dApps
+- A dApp or website don’t need to handle user's secrets (mnemonic/private keys), but can
+safely validate if a user has access to certain Ergo addresses.
+- dApp's users don't need to worry about security of their private keys as the
+wallet guarantees they never leave the device
+