// Description of the authentication-service
// It is listening on port '9004'
// Routes with a prefix 'api' are protected routes, that can only accessed with a valid ticket.

Interface Token {
    payload: {
        // The lifetime of the Token. The date in unix seconds of the expiration.
        expiresAt: date,
        // The corresponding userId of the requesting client.
        userId: number,
        // The id of the current session.
        sessionId: string
    },
    signature: string
}

Interface Cookie {
    // The id for the session corresponding to the client, who has signed in.
    sessionId: string,
    // The lifetime of a cookie. Date of expiration in unix seconds.
    exp: number,
    // Date of creation of a token in unix seconds.
    iat: number
}

// The properties of this interface have to be passed as HTTP-headers in a request. 
Interface Ticket {
    authentication: string,
    cookies: {
        refreshId: string,
        [name: string]: string
    }
}

/**
* Describes an http-response, which is sent back to any requesting service.
*/
Interface Response <T> {
    // Optional headers, which are set in an http-response
    httpHeaders: {
        // Authentication is passed, if a new access-token is returned.
        authentication?: string,
        // Cookies, like one containing 'refreshId=(Cookie as string)', if a user signs in, are passed. 
        // Lifetime of one cookie is about 24h. 
        // Flags for the cookies are: HttpOnly, Secure
        cookies: {
            [name: string]: string
        }
    }
    // This determines if a request was successful.
    success: boolean,
    // This sends back a describing message. For example, the reason of a failured request.
    message: string,
    // Optional data, which is appended, if a request was successful.
    data?: T
}

/**
* The credentials for login/authentication are not valid.
*/
Exception InvalidCredentials

/**
* POST to /system/auth/login
*
* The client can login with its credentials for authentication.
* If they are correct, the service answers with a signed Token and sets a cookie, containing the sessionId of the client.
*
* If they aren't correct, the service throws an error.
*
* @throws InvalidCredentials
*/
login (username: string, password: string): Response<void>;

/**
* POST to /system/auth/who-am-i
*
* An example for any protected route. If the client requests protected resources, it has to 
* send the signed Token and the cookie, it receives from the service at login, to the server.
*
* This will be a library to act as part of the auth-service. The other services have not to 
* request the auth-service for authentication. Instead, they use this library-function in their own
* and receive knowledge about authentication without request.
*
* Throws an exception, if the token is not valid. E.g. if the signature is not valid.
*
* @throws InvalidCredentials
*/
who-am-i (ticket: Ticket): Response<void>;

/**
* POST to /internal/auth/api/authenticate
*
* A request to get knowledge about themselves. This information is contained in the payload of 
* a Token. So, this function handles the refreshing of a Token.
*
* Sends back a new Token.
*
* Throws an exception, if the cookie is empty or the transmitted sessionId is wrong.
*
* @throws InvalidCredentials
*/
api/authenticate (ticket: Ticket): Response<LoginInformation>;

/**
* DELETE to /system/auth/api/clear-session-by-id
*
* Function to sign out one specific client from a user by its corresponding session-id.
*/
api/clear-session-by-id (sessionId: string, ticket: Ticket): Response<void> publishes LogoutSessionEvent;

/**
* POST to /system/auth/api/clear-all-session-except-themselves
*
* Function to kill all current opened sessions from one user except the one, which is requesting.
*/ 
api/clear-all-sessions-except-themselves (sessionId: string, ticket: Ticket): Response<void> publishes LogoutSessionEvent;

/**
* POST to /system/auth/api/logout
*
* The service deletes the session depending on the given Token.
*
* @throws InvalidCredentials
*/
api/logout (ticket: Ticket): Response<void> publishes LogoutSessionEvent;

/**
* GET to system/auth/api/list-sessions
*
* Returns all currently active sessions.
*
* @returns an array containing currently active sessions.
*/
api/list-sessions (ticket: Ticket): Response<{sessions: string[]}>;

/**
* POST to /internal/auth/hash
*
* Hashes a given value. A random salt (64bit) is generated and added to the hashed value.
*
* @returns the hashed value. The hashed value is structured as follows: [salt + hash].
*/
hash (toHash: string): Response<{hash: string}>;

/**
* POST to /internal/auth/is-equals
*
* Compares a given value with an given hash.
*
* @returns a boolean, if the hashed value of the given value is equals to the passed hash.
*/
is-equals (toHash: string, toCompare: string): Response<{isEquals: boolean}>;