# Web3 Authentication (Design Draft):
# Goal:
Create a simple authentication token format to let users login to web2 applications using their web3 signer keys/wallets.

# Stakeholders:
* Users:
* Wallet users (web3 account holders)
* Application users
* Builders:
* Application developers (web2/web3 devs)
* Wallet/dapp developers
* Business stakeholders (Decision makers)
* Application business stakeholders
* Wallet business stakeholders
* Security experts:
* Protocol architects
* Cryptographers
* Adversarial systems/players:
* Attackers/Hackers
* Crypto crackers
* Impersonators

# Requirements:

* Sign in:
* Easy
* Only using account keys
* App users, Wallet users
* Off-chain
* keepAlive
* Use for non-browser/non-web use cases
* Support for proxies accounts (e.x. Anonymous proxies)
* Effortless support/implementation
* Extensible:
* Multiple Chain
* Multiple account
* Multiple wallet
* Signing Protocol upgradeability
* Security
* General security
* Data theft resistant
* Identity theft resistant
* DDOS resistant
* No User/Server Impersonation
* No Signature forgery
* No Private key recovery from signature

# Token Design:
## Token Format Options:
* #### [JSON](https://www.json.org/json-en.html):
* pros:
* Serialization/Deserialization is natively supported in most of the languages.
* 1st class citizen in javascript as a most popular client side language
* Can be minimized to be compact.
* cons:
* Might not be as human readable as the others, especially when it is minimized (curly and square brackets, if minimized everything will be in one long line).

* #### [YAML](https://yaml.org/):
* pros:
* Human readable to be presented by wallets to the user when they are signing
* cons:
* Not natively supported in languages and needs third party libraries or to be implemented by developers.
* The format is not very lenient and can get error prone ( e.x tabs are not allowed, indentations can get error prone,...)
* Can not be minimized, since format relied on indentations and line breaks

* #### [TOML](https://toml.io/en/):
* pros:
* Human readable to be presented by wallets to the user when they are signing.
* cons:
* Not natively supported in languages and needs third party libraries or to be implemented by developers.
* Can not be minimized, since format relies on line breaks.

* #### XML:
Let’s don’t talk about it. The worst of all worlds!

_Both **JSON** and **TOML** sound a good choice for token format. Unlike web2, since for web3 authentications the tokens are signed by humans(users) instead of machines(servers), TOML can be considered as a more human-friendly format choice._

## Encoding:
[Base64Url](https://datatracker.ietf.org/doc/html/rfc4648#section-5) makes sense for serialization for both at rest in-storage and in transit over-the-wire.

# Token Proposals:
## JW3T (Json Web3 Token):
Inspired by [Json Web Tokens](https://datatracker.ietf.org/doc/html/rfc7519), the idea of Json Web3 Token is to design a self-contained authentication token for web3 dapps, but unlike JWTs that are issued and signed by 3rd party identity providers, JW3Ts are issued and signed by the account holders, using their key-pairs.

The token format would look like as:
xxxxxx.yyyyyy.zzzzzz

where header and payload are formatted as json objects and the signature is generated by signing ```header + "." + payload```.

### Header:
The fields in the header are explicitly specified and are used during token verification.

* ```algorithm```: the signing algorithm that is used to sign the token.
* ```address_type```: address type which specifies the derivation method to derive addresses from the public keys
* ```token_type```: specifies the token type. The value is always set to “JW3T” for Json Web3 Tokens
### Payload:
The fields in the payload are divided into two sets:

#### Verification claims:
The values of these claims are used in token verification. If the value of these claims result in an invalid token, the token should be deemed invalid and get rejected:

* ```expires_at```: Specifies the expiration time of the token on or after which the token must not be considered valid
* ```not_before```: Specifies the time before which the token must not be considered valid.
* ```address```: Specifies the address of the account that has signed the token. It should be verified against the token signature to verify it is a valid address of the account that has signed the token.

#### Information claims:
The values of these claims are not used in token verification but might be used by the application developers for authentication or authorization purposes.

some example claims:

* ```audience```: Specifies the audience of the token whom the token is issued for. A dapp or website can use the value of this claim to verify the token is issued for them.

* ```nonce```: an optional claim that contains a random arbitrary value to be used by the audience to mitigate the replay attack. It can be used to assign a token to a specific client session. The value is set by the service that sends the authentication request and is included in the token to be signed by the user.

* ```on_behalf_of```: In scenarios where proxies are supported(either known or anonymous), this claim can be used by an account to specify the address of the primary account that the signing account acts as a proxy for.

* ```proxy_type```: When the account acts as a proxy for another account this can be used to specify the proxy type which specifies the account permission level (e.x. any, governance, assets, …).

### Verification:
In order to verify a token is valid, the following steps should be followed:
* The signature should be verified to make sure it is valid.
* The claimed address in the payload ```payload.address``` should be a valid address of an account based on the address type that is specified in the header ```header.address_type``` and match the address of the account that has signed the token.
* The ```not_before``` and ```expires_at``` should be verified to make sure the token is not expired or used before it is valid.

### Example Scenario (JW3T):
#### Scenario :
A user wants to sign-in to a dapp using a proxy account.
In this scenatio, the dapp need to know the signed-in account intends to sign-in and act as a proxy (known or anonymous) for another account, so the dapp can use the correct address and wrap the transaction in a proper proxy call for the proxy account to sign.

#### Solution:
The sign-in token can achieve this by including two claims:
* ```on_behalf_of```: The on_behalf_of claim specifies the address of the primary account that the sign-in account acts as a proxy for.
* ```proxy_type```: The proxy_type claim specifies what type of proxy the proxy account represents.

#### Example JW3T:

{
“algorithm”:”sr25519”,
“address_type”:”ss58”,
“token_type”:”JW3T”
}.
{
“issued_at”:”1645921000”,
“not_before”:”1645921200”,
“expires_at”:”1645921525”,
“address”: <signed-in account address>,
“audience”:”example.dapp.io”,
“on_behalf_of”: <primary account address>,
“proxy_type”: “governance”,
“nonce”: “f77b70”
…
}

After seeing these claims in a token the app will know that any call during this sign-in session is a proxy call of type of “governance” by “signed-in account” on behalf of the specified “primary account address”.

One downside of using jw3t might be that they are not very human-friendly. Json format is machine-friendly and can be easily generated and read by machine, but might not be very human readable.

## TW3T (Toml Web3 Token):
[TOML](https://toml.io/en/) is a human-friendly serialization format that is designed to be used as a minimal configuration format which is easy to read by humans. It is designed to be more human readable than JSON and simpler than YAML. It unambiguously maps to a hash table and Its simplicity and minimal format makes it a good option for Web3 Tokens that are read and signed by humans.

A tw3t consists of a **_statement_** and a **_toml object_**, while the **_toml object_** consists of a **_token information_** section, and a **_signing specification_** section. During the signing process, a human-friendly message is generated by prepending the **_statement_** to the **_toml object_** separating them with two new line (LR) delimitters (/n/n). The token is then signed by the user according to the specified signing specification to generate a signature.

The final tw3t is generated from the concatenation of the base64Url encoding of the **_statement_**, base64Url encoding of the **_toml object_**, and base64Url encoding of the **_signature_**.

The final signed token would look like as below:
xxxxx.yyyyyy.zzzzzz

### Statement message:
An optional message which can work as a greeting to the user.

### TOML Content:
A toml table which consists of 2 sections:
#### Claim information:
The included claims will be similar to what was describe for JW3T payload.

#### Signing Specification:
The signing specification plays a similar role as JW3T header and is used in token signature verification.

### Verification:
In order to verify a token is valid, the following steps should be followed:
* The signature should be verified to make sure it is valid.
* The claimed address in the content ```toml.information.address``` should be a valid address of an account based on the address type that is specified by the specification ```toml.specification.address_type``` and match the address of the account that has signed the token.
* The ```not_before``` and ```expires_at``` should be verified to make sure the token is not expired or used before it is valid.

### Example Scenario (TW3T):
#### Scenario :
A user wants to sign-in to a dapp using a proxy account.
The dapp needs to know that the signed-in account intends to sign-in and act as a proxy (known or anonymous) for another account, so the dapp can use the correct address and wrap the related transactions in a proper proxy call for the proxy account to sign.

#### Solution:
The sign-in token can achieve this by including two claims:

#### Example TW3T:

Welcome to example.dapp.io!
Sign this message and accept the example.dapp.io Terms of Service: example.dapp.io/terms

[information]
issued_at = 2022-02-02 07:32:00Z
not_before =  2022-02-03 07:32:00Z
expires_at =  2022-02-02 07:32:00Z
address = <signed-in account address>
audience = “example.dapp.io”
on_behalf_of = <primary account address>
proxy_type = “governance”
nonce = “f88b789”

[specification]
algorithm = ”sr25519”
address_type = ”ss58”
token_type = ”TW3T”

After seeing the above claim information in a token the app will know that any call during this sign-in session is a proxy call of type of “governance” by “signed-in account” on behalf of the specified “primary account address”.

As you might have noticed, tw3t is more human readable and user-friendly than an equivalent jw3t. No curly brackets or commas! Toml also supports comments so a description can be added for each claim to let the users understand what they are signing.

A possible downside might be that the Toml format is still relatively new and does not have built-in support in programming languages which causes the libraries to rely on 3rd party dependencies or implement the toml serialization functionality.

## Proof of concept libs:
* [Json Web3 Token(JW3T)](https://github.com/hamidra/jw3t)
* [Toml Web3 Token(TW3T)](https://github.com/hamidra/tw3t)

## Community initiative
* [Login with Web3 Account](https://hackmd.io/xqF4Kb76TWK_2QndCqZQkQ?view)