NEP 0413: Add signMessage method to Wallet Standard

neps/nep-0413.md

@@ -0,0 +1,138 @@
+---
+NEP: 413
+Title: Near Wallet API - support for verifyOwner method
+Author: Philip Obosi <[email protected]>, Guillermo Gallardo <[email protected]>
+# DiscussionsTo:
+Status: Draft
+Type: Standards Track
+Category: Wallet
+Created: 25-Oct-2022
+---
+
+## Summary
+
+A standardized Wallet API method, namely `verifyOwner`, that allows users to that allows users to be authenticated in third-party services using their NEAR account.
+
+## Motivation
+NEAR users want to use their accounts as means of authentication in third-party services, in a similar fashion to how mainstream Web2 accounts can be used (e.g. "Login with Facebook").
+
+Currently, there is no standardized way for wallets to create an authentication token.
+
+## Rationale and Alternatives
+Users want to sign messages for a specific domain without incurring in GAS fees, nor compromising their account's security. This means that the message being signed:
+
+1) Must be signed off-chain, with no transactions being involved.
+2) Must include the domain's name and a nonce.
+3) Cannot represent a valid transaction.
+3) Must be signed using a Full Access Key.
+4) Should be simple to produce/verify, and transmitted securely.
+
+### Why Off-Chain?
+So the user would not incur in GAS fees, nor the signed message gets broadcasted into a public network.
+
+### Why The Message MUST NOT be a Transaction? How To Ensure This?
+An attacker could make the user inadvertently sign a valid transaction which, once signed, could be submitted into the network to execute it.
+
+#### How to Ensure the Message is not a Transaction
+In NEAR, transactions are encoded in Borsh before being signed. The first attribute of a Transaction is `signerId: string`, which is encoded as a steam of 32 bytes with the string's length, followed by the N bytes of the string itself.
+
+By prepending the string `"NEP0413:"` we can ensure that the whole message is an invalid transaction. This is because `"NEP0413:"` is `[78, 69, 80, 48]` in bytes, which borsh interprets as `810566990`. When parsing this as a transaction, Borsh will then try to read `810566990` chars (~810Mb of data), which even if present would represent an invalid account, since accounts have less than 64 chars. 
+
+### Why The Message Needs to Include a Service Identifier and Nonce?
+To stop a malicious app from requesting the user to sign a message for them, only to relay it to a third-party. Including the domain and making sure the user knows about it should mitigate this kind of attacks.
+
+Meanwhile, including a nonce helps to mitigate replay attacks, in which an attacker can delay or re-send a signed message.
+
+### Why using a FullAccess Key? Why Not Simply Creating an [FunctionCall Key](https://docs.near.org/concepts/basics/accounts/access-keys) for Signing?
+The most common flow for [NEAR user authentication into a Web3 frontend](https://docs.near.org/develop/integrate/frontend#user-sign-in--sign-out) involves the creation of a [FunctionCall Key](](https://docs.near.org/concepts/basics/accounts/access-keys)).
+
+One might feel tempted to reproduce such process here, for example, by creating a key that can only be used to call a non-existing method in the user's account. This is a bad idea because:
+1. The user would need to expend gas in creating a new key.
+2. Any third-party can ask the user to create a `FunctionCall Key`, thus opening an attack vector.
+
+Using a FullAccess key allows us to be sure that the challenge was signed by the user (since nobody should have access to their `FullAccess Key`), while keeping the constraints of not expending gas in the process (because no new key needs to be created).
+
+### How to Return the Signed Message in a Safe Way
+Sending the signed message in a query string to an arbitrary URL (even within the correct domain) is not secure as the data can be leaked (e.g. through headers, etc). Using URL fragments instead will improve security, since [URL fragments are not included in the `Referer`](https://greenbytes.de/tech/webdav/rfc2616.html#header.referer).
+
+### NEAR Signatures
+NEAR transaction signatures are not plain Ed25519 signatures but Ed25519 signatures of a SHA-256 hash (see [near/nearcore#2835](https://github.com/near/nearcore/issues/2835)). Any protocol that signs anything with NEAR account keys should use the same signature format.
+
+## Specification
+Wallets must implement a `verifyOwner` method, which takes a `message` destined to a specific `domain` and transform it into a signed message.
+
+### Input Interface
+`verifyOwner` must implement the following input interface:
+
+```jsx
+interface VerifyOwnerParams {
+  message: string ; // The message that wants to be transmitted.
+  domain: string; // The domain to whom the message is destined (e.g. "alice.near" or "myapp.com").
+  nonce: [u8; 32] ; // A nonce that uniquely identifies this instance of the message
+  callbackUrl?: string; // Optional, applicable to browser wallets (e.g. MyNearWallet). The URL to call after the signing process. Defaults to `window.location.href`.
+}
+```
+
+### Structure
+`verifyOwner` must embed the input `message`, `domain` and `nonce` into the following predefined structure:
+
+```rust
+struct Payload {
+  message: string; // The same message passed in `VerifyOwnerParams.message`
+  domain: string; // The same domain passed in `VerifyOwnerParams.domain`
+  nonce: [u8; 32]; // The same nonce passed in `VerifyOwnerParams.nonce`
+}
+```
+
+### Signature
+In order to create a signature, `verifyOwner` must:
+1. Convert the `Payload` into its [JSON JCS](https://www.rfc-editor.org/rfc/rfc8785) string representation (i.e. a JSON string, with alphabetically ordered attributes).
+2. Prepend the `NEP0413:` string to the result from step 1.
+3. Compute the `SHA256` hash of the result from step 2.
+4. Sign the resulting `SHA256` hash from step 3 using a **full-access** key.
+
+> If the wallet does not hold any `full-access` keys, then it must return an error.
+
+### Example
+Assuming that the `verifyOwner` method was invoked, and that:
+- The input `message` is `"hi"`
+- The input `domain` is `"myapp.com"`
+- The input `nonce` is `[0,...,31]`
+- The wallet stores a full-access private key
+
+The wallet must construct and sign the following `SHA256` hash:
+
+```jsx
+sha256.hash(`NEP0413:` + `{"message":"hi","domain":"myapp.com","nonce":"[0,...,31]"}`)
+```
+
+### Output Interface
+`verifyOwner` must return an object containing the **base64** representation of the `signature`, and all the data necessary to verify such signature. 
+
+```jsx
+interface VerifyOwnerOut {
+  accountId: string; // The account name to which the publicKey corresponds as plain text (e.g. "alice.near")
+  publicKey: string; // The public counterpart of the key used to sign, expressed as a string with format "<key-type>:<base-64-key-bytes>"
+  signature: string; // The base64 representation of the signature.
+}
+```
+
+### Returning the signature
+#### Web Wallets
+Web Wallets, such as [MyNearWallet](https://mynearwallet.com), should directly return the `AuthenticationToken` to the `VerifyOwnerParams.callbackUrl`, passing both `accountId` and `publicKey` as strings, and the `signature` as an URL fragment. This is: `<callbackUrl>?accountId=<accountId>&publicKey=<publicKey>#signature=<signature>`.
+
+If the signing process fails, then the wallet must return an error message as a string parameter: `<callbackUrl>?error=<error-message-string>`.
+
+#### Other Wallets
+Non-web Wallets, such as [Ledger](https://www.ledger.com) can directly return the `VerifyOwnerOut` (in preference as a JSON object) and raise an error on failure.
+
+## References
+A full example on how to implement the `verifyOwner` method can be [found here](https://github.com/gagdiez/near-login/blob/main/tests/authentication/auth.ava.ts#L27-#L65).
+
+## Drawbacks
+Accounts that do not hold a FullAccess Key will not be able to sign this kind of messages. However, this is a necessary tradeoff for security since any third-party can ask the user to create a FunctionAccess key.
+
+## Copyright
+[copyright]: #copyright
+
+Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).