SEP-0010: Add back home domain verification with clarity (v3.0.0)

ecosystem/sep-0010.md

@@ -18,12 +18,18 @@ This SEP defines the standard way for clients such as wallets or exchanges to cr
 
 This protocol is a variation of mutual challenge-response, which uses Stellar transactions to encode challenges and responses.
 
+It involves three parties:
+- A home domain hosting a [SEP-1 stellar.toml](sep-0001.md) containing a `WEB_AUTH_ENDPOINT` value.<sup>[1](#note1)</sup>
+- A web auth endpoint providing the GET and POST operations discussed in this document.
+- A client.
+
 The authentication flow is as follows:
 
-1. The client obtains a unique [`challenge`](#challenge), which is represented as specially formed Stellar transaction
+1. The client obtains the `WEB_AUTH_ENDPOINT` for the service by getting the [SEP-1 stellar.toml](sep-0001.md) from the services domain, referred to as the home domain. The home domain hosts the stellar.toml.
+1. The client obtains a unique [`challenge`](#challenge) from the `WEB_AUTH_ENDPOINT`, which is represented as specially formed Stellar transaction
 1. The client verifies that the transaction has an invalid sequence number 0.  This is extremely important to ensure the transaction isn't malicious.
 1. The client verifies that the transaction is signed by the `SIGNING_KEY` specified by the requested service's [SEP-1 stellar.toml](sep-0001.md).
-1. The client verifies that the transaction has a single Manage Data operation with its source account set to the user's account and value set to a nonce value. The client ignores the home domain included.
+1. The client verifies that the transaction has a single Manage Data operation with its source account set to the user's account and value set to a nonce value. The client verifies the home domain included is the domain from the first step.
 1. The client verifies that if the transaction has other Manage Data operations they all have their source accounts set to the the server's account.
 1. The client signs the transaction using the secret key(s) of signers for the user's Stellar account
 1. The client submits the signed challenge back to the server using [`token`](#token) endpoint
@@ -50,6 +56,9 @@ The flow achieves several things:
 * The server can choose to include other application specific claims
 * The server can choose to authenticate accounts that do not yet exist
 
+Notes:
+1. <a name="note1"></a>Some use cases of SEP-10 may not involve a home domain. See the relevant notes throughout.
+
 ## Authentication Endpoint
 
 A web service indicates that it supports user authentication via this protocol by specifying `WEB_AUTH_ENDPOINT` in their [`stellar.toml`](sep-0001.md) file. This is how a wallet knows where to find the authentication server. A web server is required to implement the following behavior for the web authentication endpoint:
@@ -69,7 +78,9 @@ In order for browsers-based wallets to validate the CORS headers, as [specified
 
 ### Challenge
 
-This endpoint must respond with a Stellar transaction signed by the server that has an invalid sequence number (0) and thus cannot be executed on the Stellar network. The client can then sign the transaction using standard Stellar libraries and submit it to [`token`](#token) endpoint to prove that they control their account. This approach is compatible with hardware wallets such as Ledger. The client must also verify the server's signature to be sure the challenge is signed by the `SIGNING_KEY` from the server's [`stellar.toml`](sep-0001.md).
+This endpoint must respond with a Stellar transaction signed by the server that has an invalid sequence number (0) and thus cannot be executed on the Stellar network. The client can then sign the transaction using standard Stellar libraries and submit it to [`token`](#token) endpoint to prove that they control their account. This approach is compatible with hardware wallets such as Ledger. The client must also verify the server's signature to be sure the challenge is signed by the `SIGNING_KEY` from the server's [`stellar.toml`](sep-0001.md), and the home domain in the challenge is the domain of the domain hosting the [`stellar.toml`](sep-0001.md).
+
+Client and server arrangements where a client connects directly to a hardcoded server without interacting with a home domain hosting a stellar.toml may verify the signing key and home domain using other methods not defined here. The client should still perform verification of these values, and the home domain should be unique in a way similar to if a home domain was in use. For example, the home domain could be defined as the domain of the SEP-10 server.
 
 #### Request
 
@@ -82,7 +93,7 @@ Request Parameters:
 Name      | Type          | Description
 ----------|---------------|------------
 `account` | `G...` string | The stellar account that the wallet wishes to authenticate with the server
-`home_domain` | string | (optional) The [fully qualified domain name](https://en.wikipedia.org/wiki/Fully_qualified_domain_name) of the service requiring authentication. SEP-10 signing servers used to generate tokens for multiple different web services can use this parameter to create valid tokens for each service. If not provided by the client, a default should be used.
+`home_domain` | string | (optional) The home domain the client would like to authenticate for. Servers that generate tokens for multiple home domains can use this parameter to create valid tokens for each service. If not provided by the client, the server should assume a default for backwards compatibility with older clients.
 
 Example:
 
@@ -100,7 +111,7 @@ On success the endpoint must return `200 OK` HTTP status code and a JSON object
   * time bounds: `{min: now(), max: now() + 900 }` (we recommend expiration of 15 minutes to give user time to sign transaction)
   * operations:
     * `manage_data(source: client_account, key: '<home domain> auth', value: random_nonce())`
-      * The value of key is the fully qualified domain name of the web service requiring authentication followed by `auth`. It can be at most 64 characters.
+      * The value of key is the home domain the challenge is providing authentication for, followed by `auth`. It can be at most 64 characters.
       * The value must be 64 bytes long. It contains a 48 byte cryptographic-quality random string encoded using base64 (for a total of 64 bytes after encoding).
     * zero or more `manage_data(source: server_account, ...)` reserved for future use
   * signature by the service's stellar.toml `SIGNING_KEY`
@@ -140,6 +151,7 @@ To validate the challenge transaction the following steps are performed by the s
 * verify that transaction has time bounds set, and that current time is between the minimum and maximum bounds;
 * verify that transaction contains a single [Manage Data](https://www.stellar.org/developers/guides/concepts/list-of-operations.html#manage-data) operation that:
   * has a non-null source account
+  * has the home domain as the key of the operation
 * verify that transaction envelope has a correct signature by server's signing key;
 * if the operation's source account exists:
   * verify that client signatures count is one or more;