Servant.API.Auth.Token

API specs

type AuthAPI = AuthSigninMethod :<|> (AuthTouchMethod :<|> (AuthTokenInfoMethod :<|> (AuthSignoutMethod :<|> (AuthSignupMethod :<|> (AuthUsersMethod :<|> (AuthGetUserMethod :<|> (AuthPatchUserMethod :<|> (AuthPutUserMethod :<|> (AuthDeleteUserMethod :<|> (AuthRestoreMethod :<|> (AuthGetGroupMethod :<|> (AuthPostGroupMethod :<|> (AuthPutGroupMethod :<|> (AuthPatchGroupMethod :<|> (AuthDeleteGroupMethod :<|> AuthGroupsMethod)))))))))))))))

Generic authorization API

type AuthSigninMethod = "auth" :> ("signin" :> (QueryParam "login" Login :> (QueryParam "password" Password :> (QueryParam "expire" Seconds :> Get `[JSON]` (OnlyField "token" SimpleToken)))))

How to get a token, expire of Nothing means some default value (server config)

type AuthTouchMethod = "auth" :> ("touch" :> (QueryParam "expire" Seconds :> (TokenHeader `[]` :> Post `[JSON]` ())))

Client cat expand the token lifetime, no permissions are required

type AuthTokenInfoMethod = "auth" :> ("token" :> (TokenHeader `[]` :> Get `[JSON]` RespUserInfo))

Get client info that is binded to the token

type AuthSignoutMethod = "auth" :> ("signout" :> (TokenHeader `[]` :> Post `[JSON]` ()))

Close session, after call of the method the token in header is not valid.

type AuthSignupMethod = "auth" :> ("signup" :> (ReqBody `[JSON]` ReqRegister :> (TokenHeader `["auth-register"]` :> Post `[JSON]` (OnlyField "user" UserId))))

Creation of new user, requires registerPerm for token

type AuthUsersMethod = "auth" :> ("users" :> (PageParam :> (PageSizeParam :> (TokenHeader `["auth-info"]` :> Get `[JSON]` RespUsersInfo))))

Getting list of all users, requires authInfoPerm for token

type AuthGetUserMethod = "auth" :> ("user" :> (Capture "user-id" UserId :> (TokenHeader `["auth-info"]` :> Get `[JSON]` RespUserInfo)))

Getting info about user, requires authInfoPerm for token

type AuthPatchUserMethod = "auth" :> ("user" :> (Capture "user-id" UserId :> (ReqBody `[JSON]` PatchUser :> (TokenHeader `["auth-update"]` :> Patch `[JSON]` ()))))

Updating loginemailpassword, requires authUpdatePerm for token

type AuthPutUserMethod = "auth" :> ("user" :> (Capture "user-id" UserId :> (ReqBody `[JSON]` ReqRegister :> (TokenHeader `["auth-update"]` :> Put `[JSON]` ()))))

Replace user with the user in the body, requires authUpdatePerm for token

type AuthDeleteUserMethod = "auth" :> ("user" :> (Capture "user-id" UserId :> (TokenHeader `["auth-delete"]` :> Delete `[JSON]` ())))

Delete user from DB, requires authDeletePerm and will cause cascade deletion, that is your usually want

type AuthRestoreMethod = "auth" :> ("restore" :> (Capture "user-id" UserId :> (QueryParam "code" RestoreCode :> (QueryParam "password" Password :> Post `[JSON]` ()))))

Generate new password for user. There is two phases, first, the method is called without code parameter. The system sends email with a restore code to user email or sms (its depends on server). After that a call of the method with the code is needed to change password.

type AuthGetGroupMethod = "auth" :> ("group" :> (Capture "group-id" UserGroupId :> (TokenHeader `["auth-info"]` :> Get `[JSON]` UserGroup)))

Getting info about user group, requires authInfoPerm for token

type AuthPostGroupMethod = "auth" :> ("group" :> (ReqBody `[JSON]` UserGroup :> (TokenHeader `["auth-update"]` :> Post `[JSON]` (OnlyId UserGroupId))))

Inserting new user group, requires authUpdatePerm for token

type AuthPutGroupMethod = "auth" :> ("group" :> (Capture "group-id" UserGroupId :> (ReqBody `[JSON]` UserGroup :> (TokenHeader `["auth-update"]` :> Put `[JSON]` ()))))

Replace info about given user group, requires authUpdatePerm for token

type AuthPatchGroupMethod = "auth" :> ("group" :> (Capture "group-id" UserGroupId :> (ReqBody `[JSON]` PatchUserGroup :> (TokenHeader `["auth-update"]` :> Patch `[JSON]` ()))))

Patch info about given user group, requires authUpdatePerm for token

type AuthDeleteGroupMethod = "auth" :> ("group" :> (Capture "group-id" UserGroupId :> (TokenHeader `["auth-delete"]` :> Delete `[JSON]` ())))

Delete all info about given user group, requires authDeletePerm for token

type AuthGroupsMethod = "auth" :> ("group" :> (PageParam :> (PageSizeParam :> (TokenHeader `["auth-info"]` :> Get `[JSON]` (PagedList UserGroupId UserGroup)))))

Get list of user groups, requires authInfoPerm for token

authAPI :: Proxy AuthAPI

Proxy type for auth API, used to pass the type-level info into client/docs generation functions

authDocs :: API

Servant.Docs documentation of the Auth API

Token

newtype Token perms

Token is simple string marked by permissions that are expected from the token to pass guarding functions.

Constructors

Token

Fields

unToken :: Text

Instances

Eq (Token perms)

Show (Token perms)

FromHttpApiData (Token perms)

ToHttpApiData (Token perms)

ToSample (Token perms)

ToParamSchema (Token perms)

type MToken perms = Maybe (Token perms)

Shortcut for Maybe Token with attached permissions

type TokenHeader perms = Header "Authorization" (Token perms)

Token header that we require for authorization marked by permissions that are expected from the token to pass guarding functions.

type SimpleToken = Text

Token that doesn't have attached compile-time permissions

class PermsList a where

Methods

unliftPerms :: forall proxy. proxy a -> [Permission]

Instances

PermsList ([] Symbol)

(KnownSymbol x, PermsList xs) => PermsList ((:) Symbol x xs)

downgradeToken' :: (True ~ PermsSubset ts' ts) => Token ts -> Token ts'

Cast token to permissions that are lower than original one

The cast is safe, the permissions are cheked on compile time.

downgradeToken :: (True ~ PermsSubset ts' ts) => MToken ts -> MToken ts'

Cast token to permissions that are lower than original one.

The cast is safe, the permissions are cheked on compile time.

User

type UserId = Word

Id of user that is used in the API

type Login = Text

User name for login

type Password = Text

Password for login

type Email = Text

User email

type Permission = Text

Special tag for a permission that a user has

type Seconds = Word

Amount of seconds

type RestoreCode = Text

Special tag for password restore

data ReqRegister

Request body for user registration

Constructors

ReqRegister

Fields

reqRegLogin :: !Login

reqRegPassword :: !Password

reqRegEmail :: !Email

reqRegPermissions :: ![Permission]

reqRegGroups :: !(Maybe [UserGroupId])

Instances

Show ReqRegister

Generic ReqRegister

ToJSON ReqRegister

FromJSON ReqRegister

ToSchema ReqRegister

ToSample ReqRegister

type Rep ReqRegister

data RespUserInfo

Response with user info

Constructors

RespUserInfo

Fields

respUserId :: !UserId

respUserLogin :: !Login

respUserEmail :: !Email

respUserPermissions :: ![Permission]

respUserGroups :: ![UserGroupId]

Instances

Show RespUserInfo

Generic RespUserInfo

ToJSON RespUserInfo

FromJSON RespUserInfo

ToSchema RespUserInfo

ToSample RespUserInfo

type Rep RespUserInfo

data PatchUser

Request body for patching user

Constructors

PatchUser

Fields

patchUserLogin :: !(Maybe Login)

patchUserPassword :: !(Maybe Password)

patchUserEmail :: !(Maybe Email)

patchUserPermissions :: !(Maybe [Permission])

patchUserGroups :: !(Maybe [UserGroupId])

Instances

Show PatchUser

Generic PatchUser

ToJSON PatchUser

FromJSON PatchUser

ToSchema PatchUser

ToSample PatchUser

type Rep PatchUser

data RespUsersInfo

Response with users info and pagination

Constructors

RespUsersInfo

Fields

respUsersItems :: ![RespUserInfo]

respUsersPages :: !Word

Instances

Show RespUsersInfo

Generic RespUsersInfo

ToJSON RespUsersInfo

FromJSON RespUsersInfo

ToSchema RespUsersInfo

ToSample RespUsersInfo

type Rep RespUsersInfo

User groups

type UserGroupId = Word

Id of user group

data UserGroup

Data of user group, groups allows to group permissions and assign them to particular users in batch manner.

Also a group hierarchy can be formed.

Constructors

UserGroup

Fields

userGroupName :: !Text

userGroupUsers :: ![UserId]

userGroupPermissions :: ![Permission]

userGroupParent :: !(Maybe UserGroupId)

Instances

Show UserGroup

Generic UserGroup

ToJSON UserGroup

FromJSON UserGroup

ToSchema UserGroup

ToSample UserGroup

type Rep UserGroup

data PatchUserGroup

Data type that is used to patch UserGroup

Constructors

PatchUserGroup

Fields

patchUserGroupName :: !(Maybe Text)

patchUserGroupUsers :: !(Maybe [UserId])

patchUserGroupPermissions :: !(Maybe [Permission])

patchUserGroupParent :: !(Maybe UserGroupId)

patchUserGroupNoParent :: !(Maybe Bool)

Special case when you want to set parent to Nothing

Instances

Show PatchUserGroup

Generic PatchUserGroup

ToJSON PatchUserGroup

FromJSON PatchUserGroup

ToSchema PatchUserGroup

ToSample PatchUserGroup

type Rep PatchUserGroup

Default permissions

adminPerm :: Permission

Permission that allows everything by default

registerPerm :: Permission

Permission that allows registration of new users

authInfoPerm :: Permission

Permission that allows to query info about other users

authUpdatePerm :: Permission

Permission that allows to update fields of an user

authDeletePerm :: Permission

Permission that allows to delete users and cause cascade deletion

Swagger helpers

authOperations :: Traversal' Swagger Operation

Select only operations of the Auth API

Reexports