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-12-02
-Version 1.2.0
+Updated: 2019-12-04
+Version 1.3.0
 ```
 
 ## 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 for the user's Stellar account
 1. The client submits the signed challenge back to the server using [`token`](#token) endpoint
+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), if any
 1. If the signature checks out, 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 verify that the client holds the secret key(s) to signers of 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(s)
 * The server can choose its own timeout for the user's session
+* The server can choose required threshold(s) that the user needs on the account, if any
+* The server can choose to include other application specific claims
 
 ## Authentication Endpoint
 
@@ -122,16 +127,31 @@ 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 and its 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;
+* if the operations source account exists:
+  * verify that client signatures count is one or more;
+  * verify that client signatures on the transaction 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), if any;
+* if the operations source account does not exist:
+  * verify that client signature count is one;
+  * verify that client signature is correct for the master key of the account address;
 * verify that transaction sequenceNumber is equal to zero;
 * use operations's source account to determine the authenticating client and perform any additional service-specific validations.
 
+The verification process goal is to confirm that a user holds an account. Depending on your application this may mean complete signing authority, some threshold of control, or being a signer of the account.
+
+A server that needs to verify a user has complete signing authority of an account should verify that the weight of the client signatures meet all thresholds of the account. It should do this by checking that the sum of the weights is equal or greater to all the thresholds: low, mid and high. The server should only issue a JWT if all thresholds are met. When determining the weight of the client signatures the server's signature should be explicitly excluded as it may be a signer on the account and a server verifying authentication should not help the client authenticate.
+
+A server may choose to issue JWTs for less than all thresholds and based on any other application specific logic.
+
+A server that needs to support validating accounts that do not exist can require a signature of the master key of the account address.
+
 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`)
+* `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 (`1530730493`)
 
 The JWT may contain other claims specific to your application, see [RFC7519].
 
@@ -187,6 +207,10 @@ Every other HTTP status code will be considered an error. For example:
 }
 ```
 
+## JWT Expiration
+
+Servers should select an expiration time for the JWT that is appropriate for the assumptions and risk of the interactions a user can perform with it. A user may be in control of an account at the time the JWT is issued but they may lose control of the account through a change in signers. Expiration times that are too long increase the risk that control on the account has changed. Expiration times that are too short increase the number of times authentication must reoccur, and a user using a hardware signing device or who must complete a complex signing process could have a poor user experience.
+
 ## 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: