# KeyConnect API

RESTful API written in *Node.js* utilizing Ethereum for authentication, authorization and secret sharding.

KeyConnect acts as a trusted third party between client applications and server systems.

## Authentication

KeyConnect Authorization API is based on ECDSA signatures for issuing security JWT tokens.

Client applications ask for a **sign request** or **challenge**. The end-user (resource owner) needs to sign the request and submit it for token issuance. If the signature passes validation, KeyConnect issues a JWT signed with the apps RSA key.

TODO: Add endpoints with detailed specification

## Sharding

#### POST /keyconnect/store

Issues request for storing sharded ethereum private key(mnemonics).

Request:

{
    'ethereumAddress' : 'string',
    'dappName' : 'string',
    'shards' : ['shard1', 'shard2', 'shard3', 'shard4', 'shard5'],
    'keyConnectShards' : 'int',
    'addresses' : [ 'address1', 'address2', 'address3'],
    'backupShardHolders' : "bool"
}

`dappName` - name of the application where `ethereumAddress` is used
`keyConnectShard` - number of shards that KeyConnect stores
`backupShardHolders` - indicator if KeyConnect should store list of shard holders

Response:

201 Created
{
}

#### GET /keyconnect/queue/store

Returns a list of shard information of pending store requests.

Response:

{
    'result': [
        {
            'ethereumAddress': 'shard creator's address',
            'userName': 'string or email',
            'dappName': 'string',
            'shardId': 'string',
            'shardString': 'string'
        },
        ...
    ]
}

#### POST /keyconnect/queue/store

Route used for giving consents on stored shards.

Request:

{
    'ethereumAddress': 'shard-holder-address',
    'shardId': 'string',
    'consent': 'bool'
}

Response:

200 OK 
{
}

#### POST /keyconnect/restore

Issues request for restoring of saved shards in system.

Request:

{
    'ethereumAddress': 'eth-address',
    'dappName': 'string',
    'shardHolders': {
        'keyConnectShards': 'integer',
        'addressList': [ ... ]
    }
    
}

`keyConnectShards` - number of KeyConnect shards used for restoring private key (0, 1 or 2)
`addressList` - list of friend addresses that store the sender's shards and that are requested to restore sender's private key (NOTE: length should be `3 - keyConnectShards`)

#### GET /keyconnect/queue/restore

Request on this route checkes if there are any pending requests for restoring waiting on the user that sent the request.

Response:

200 OK
{
    'result': [
        {
            'ethereumAddress': 'secret-owner-eth-address',
            'dappName': 'string',
            'userName': 'string',
            'shardId': 'string'
        },
        ...
    ]
}

`ethereumAddress` - address of the secret owner
`shardId` - id of the shard that the given user gave consent to store (NOTE: not the shardString)

#### POST /keyconnect/queue/restore

Returns stored shard back to the system.

Request:

{
    'shardId': 'string',
    'shardString': 'string'
}

Response:

202 Accepted
{
}

#### GET /keyconnect/restore

Restores original secret from shards.

Response:

{
    'result': [
        {
            'ethereumAddress': 'eth-address',
            'dappName': 'string',
            'shards': 
            [
                {
                    'shardId': 'string',
                    'shardString': 'string'
                }
            ]
        }
    ]
}