# User authentication in Host Console and HoloFuel

## Context

Host Console UI and HoloFuel UI in Host context connect directly to APIs of Holoport. For this connection to be secure there's an authentication mechanism needed. Currently Host Console UI is collecting user's login and password. From those values a pub-priv keypar is generated used for signing HTTP requests to Holoport's APIs. On Holoport's side signature is checked against stored PubKey.

One of the requirements for this authenticatoin process is that multiple UIs share same authentication mechanism so that user does not have to re-login while switching between UIs.

One way to achieve this is to store authentication credentials in localStorage.

### Storing login credentials in localStorage

Storing permanent secrets is considered insecure, because once stolen they give attacker full access to user's account. In case of Host Console it is even worse, because there is no mechanism for changing login credentials. So once secret is stolen (in form of login & password pair, or in form of a private signing key) user exposes to attecker their holoport for ever.

## More secure authentication method

This method uses disposable `auth-token` for http requests to `hpos-holochain-api` and wss UPGRADE.

Token has expiery date and can be revoked.

Token transfer between UI and holoport is secured with help of signature created by UI and checked on Holoport.

#### First time login (no tokens in localStorage):

sequenceDiagram
participant A as Host Console
participant B as Auth server
participant C as hpos-holochain-api
participant D as Holochain
    Note over A: /login/
    Note over A: Create WASM instance with keys
    Note over A: Create X-signature header
    Note over A: Create random auth-token
    Note over A: Create X-Hpos-Auth-Token header
    A-->>B: any HTTP call
    Note over B: Check X-signature-header
    Note over B: Read X-Hpos-Auth-Token
    Note over B: Save auth-token in memory
    B-->>A: 200
    Note over A: Save auth-token in localStorage under key authToken
    Note over A: Delete WASM instance with keys

#### Use tokens from localStorage:

sequenceDiagram
participant A as Host Console
participant B as Auth server
participant C as hpos-holochain-api
participant D as Holochain
    opt http request
        Note over A: Read auth-token form localStorate under key authToken
        Note over A: Create X-Hpos-Auth-Token header
        A-->>B: GET /api/v1/config
        Note over B: Check X-Hpos-Auth-Token header
        B-->>C: GET /api/v1/config
        C-->>A: Return response
    end
    opt wss
        Note over A: Open wss connection to Holochain
        Note over A: Create X-Hpos-Auth-Token header
        A-->>B: UPGRADE wss
        Note over B: Check X-Hpos-Auth-Token
        B-->>D: 
        Note over D: Open wss connection
        D-->>A: 100
    end

#### Log out:
Delete `authToken` from local storage

#### Token revocation:
first log out (wipe `authToken` from localStorage), then log in again. This will create new token and wipe out old one on server side.

## Note on wss connection to holochain

Holochain will soon offer UI cap tokens. Those could be used for authentication directly in Holochain. IMHO we should stick to `auth-token` based mechanism, because once authentication is handled by nginx only authenticated calls reach Holochain. This is important in case of DOS attack. If all the authentication requests were reaching Holochain's workflow queue it would be very easy to overwhelm Holochain and block its hosting capabilities.

## Code logic

### HP Admin Auth server

flowchart TD
    A(check if X-auth-token header is set)
    A-->|no|C
    A-->|yes|G
    G(check if X-signature header is set)
    G-->|yes|J
    J(verify signature)
    J-->|ok|H
    H(save authToken in memory)
    J-->|fail|K
    K(return 401)
    H-->I
    I(return 200)
    G-->|no|B
    B(check authToken aginst in-memory)
    B-->|fail|D
    D(return 401)
    B-->|ok|E
    E(save authToken's new create time)
    E-->L
    L(return 200)
    C(return 401)

### HC UI

HTTP call creates `X-Hpos-Auth-Token` header first:

flowchart TD
    A(check localStorage for authToken)
    A-->|yes|B
    B(return authToken)
    A-->|no|C
    C(check for signing wasm existence)
    C-->|no|D
    D(redirect to login)
    C-->|yes|E
    E(create signature)
    E-->F
    F(create authToken)
    F-->G
    G(make wrapped HTTP)
    G-->|401|H
    H(redirect to login)
    G-->|200|I
    I(save authToken in localStorage)
    I-->J
    J(delete signing wasm)
    J-->K
    K(return authToken)

> Wrapper around HTTP request:
call that returns 401 deletes authToken key from localStorage and redirects to login

### HF UI

WSS connection passes query param `X-Hpos-Auth-Token` taken from localStorage key authToken (null if it does not exist).

For 401 (or failure to open wss?) delete authToken from localStorage and redirect to login

> It would be nice to distingush between 401 and failure to open wss