SEP-10: Add multi-sig capabilities

ecosystem/sep-0010.md

@@ -3,11 +3,11 @@
 ```
 SEP: 0010
 Title: Stellar Web Authentication
-Author: Sergey Nebolsin <[email protected]>, Tom Quisel <[email protected]>
+Author: Sergey Nebolsin <[email protected]>, Tom Quisel <[email protected]>, Leigh McCulloch <@leighmcculloch>
 Status: Active
 Created: 2018-07-31
-Updated: 2019-11-22
-Version 1.1.1
+Updated: 2019-12-04
+Version 1.2.1
 ```
 
 ## Simple Summary
@@ -22,18 +22,23 @@ 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 verifies that the transaction has an invalid sequence number 0.  This is extremely important to ensure the transaction isn't malicious.
-1. The client signs the transaction using the secret key for the user's Stellar account
+1. The client signs the transaction using the secret key(s) of signers of the user's Stellar account
 1. The client submits the signed challenge back to the server using [`token`](#token) endpoint
-1. If the signature checks out, the server responds with a [JWT](https://jwt.io) that represents the user's session
+1. The server gets the signers of the user's account
+1. The server verifies the signatures
+1. The server verifies the weight provided by the signers meets the required threshold(s)
+1. The server responds with a [JWT](https://jwt.io) that represents the user's session
 1. Any future calls to the server can be authenticated by including the JWT as a parameter
 
 The flow achieves several things:
 
 * Both client and server part can be implemented using well-established Stellar libraries
-* The client can verify that the server holds the secret key to a particular account
-* The server can verify that the client holds the secret key to their account
-* The client is able to prove their identity using a Ledger or other hardware wallet as well as by having direct access to the secret key
-* The server can chose its own timeout for the user's session
+* The client can verify that the server holds the secret key to a particular public key
+* The server can verify that the client holds the secret key(s) of signers of the user's Stellar account
+* The client is able to prove their identity using a Ledger or other hardware wallet as well as by having direct access to the secret key(s)
+* The server can choose its own timeout for the user's session
+* The server can choose the required threshold(s) a user needs on the account
+* Other servers can choose the required threshold(s) a user needs on the account for specific functionality
 
 ## Authentication Endpoint
 
@@ -54,7 +59,7 @@ 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 can 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 and multiple signatures can be included for accounts with multiple signers. The client can 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).
 
 #### Request
 
@@ -120,19 +125,28 @@ To validate the challenge transaction the following steps are performed by the s
 * decode the received input as a base64-urlencoded XDR representation of Stellar transaction envelope;
 * verify that transaction source account is equal to the server's signing key;
 * 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 and it's source account is not null;
-* verify that transaction envelope has a correct signature by server's signing key;
-* verify that transaction envelope has a correct signature by the operation's source account;
+* verify that transaction contains a single [Manage Data](https://www.stellar.org/developers/guides/concepts/list-of-operations.html#manage-data) operation and its source account is not null;
 * verify that transaction sequenceNumber is equal to zero;
+* verify that transaction envelope has a correct signature by server's signing key;
+* verify that client signatures on the transactions are signers of the operations source account;
+* verify that client signatures are correct;
+* verify that client signatures provide weight that meets the required threshold(s);
 * use operations's source account to determine the authenticating client and perform any additional service-specific validations.
 
+When determining the weight of the signers the server's signer should be excluded, even if it is a signer on the account. In most cases the server should verify that the signers meet all thresholds of the account by checking that the sum of the weights is equal or greater to the low, mid and high thresholds, and fail to issue a JWT if all thresholds are not met. Some servers may have use cases to issue JWTs for less than all thresholds.
+
 Upon successful validation service responds with a session JWT, containing the following claims:
 
 * `iss` (the principal that issued a token, [RFC7519, Section 4.1.1](https://tools.ietf.org/html/rfc7519#section-4.1.1)) — a [Uniform Resource Identifier (URI)] for the issuer (`https://example.com` or `https://example.com/G...`)
 * `sub` (the principal that is the subject of the JWT, [RFC7519, Section 4.1.2](https://tools.ietf.org/html/rfc7519#section-4.1.2)) — the public key of the authenticating Stellar account (`G...`)
 * `iat` (the time at which the JWT was issued [RFC7519, Section 4.1.6](https://tools.ietf.org/html/rfc7519#section-4.1.6)) — current timestamp (`1530644093`)
 * `exp` (the expiration time on or after which the JWT must not be accepted for processing, [RFC7519, Section 4.1.4](https://tools.ietf.org/html/rfc7519#section-4.1.4)) — a server can pick its own expiration period for the token, however 24 hours is recommended (`1530730493`)
 * `jti` (the unique identifier for the JWT, [RFC7519, Section 4.1.7](https://tools.ietf.org/html/rfc7519#section-4.1.7)) — hex-encoded hash of the challenge transaction (`f0e754c6ab988eb5fb2811c2cacc4d3d2aa4334763b8df7285ef341921e2530a`)
+* `thr`
+  * `low` — low threshold of the account
+  * `med` — medium threshold of the account
+  * `high` — high threshold of the account
+* `wht` — weight of the signers who signed the challenge transaction, excluding the weight of the server signer if it is also a signer of the account
 
 The JWT may contain other claims specific to your application, see [RFC7519].
 
@@ -188,6 +202,12 @@ Every other HTTP status code will be considered an error. For example:
 }
 ```
 
+## Validating the JWT
+
+Services that use the JWT as proof the user meets a threshold of control of a Stellar account need to validate the JWT. General [JWT best practices](#jwt-best-practices) should be followed for validating the claims within the header and payload. If the JWT contains threshold (`thr`) and weight (`wht`) claims the service should check that the threshold required by that service is met.
+
+Some versions of SEP-10 did not include the `thr` and `wht` and if the claims are not present the service can assume all thresholds were met.
+
 ## A convention for signatures
 
 Signatures in Stellar involve both the secret key of the signer and the passphrase of the network. SEP-10 clients and servers must use the following convention when deciding what network passphrase to use for signing and verifying signatures in SEP-10: