MOTH

Basic token based authentication server

Components

CLI

The MOTH CLI is very limited and only contains two commands.

The first command is moth create. This takes a file path and creates an empty MOTH database file.
The second command is moth run. This takes the path to a MOTH database and a server port, and starts the server.

Server

This can be accessed through moth.server. It has two main methods: run and run_threaded.
Both take a database path and a server port, with the difference being that run_threaded starts the server without blocking.

Moth

This is an alternate method of accessing MOTH without the use of the server accessible through the moth.moth.Moth class.
The functions in this class mirror the API endpoints of moth.server.

Utils

This is a collection of MOTH utilities, exceptions, and other internal classes accessible through moth.utils.
There are 3 primary functions included:

• db_exists takes a path to a database file and returns whether it exists or not.
• make_db takes a path and creates a new database file at it if a database is not already present there. It will return if a new databse was created or not.
• reset_db takes a path to an existing database file and resets if it is present. It will not create a new database. It will return if it reset the database.

API

Note that while these docs cover the server API, the moth.moth.Moth class functions take the same names and parameters. For example, sending {"token"="TOKEN"} to /logout is equivalent to running logout(token="TOKEN").
The largest difference is that non-200 return codes are replaced with exceptions. The only return code that does not have an exception analogue is 400 Missing request parameters. All server end points are capable of responding with it.
Many methods return either 401 Token expired or moth.utils.TokenExpiredError. This indicates that a token did exist, but has expired. This also means that the token has been cleaned up, and subsequent identical calls will return 401 Token does not exist or moth.utils.InvalidTokenError.

Terms

• username: The name of the user account
• password: The password of the user account
• token: An access token associated with an account
• userid or id: An internal unique incremental ID associated with each account
• permissions: A miscellaneous convenience string. This is not used within MOTH itself.
• expires: A unix timestamp at which the associated token expires.
• valid: A boolean stating if the requested resource is valid or not.
• deleted: A boolean stating if the requested resource has been successfuly deleted.
• updated: A boolean stating if the requested resource has been successfuly updated.
• count: An integer representing the amount of matching resources present.

/login [GET]

Create and return a user token.
Equivalent method: login
Takes: username, password
Returns: token, userid, username, permissions, expires
Error codes:

• 401 User does not exist or moth.utils.NoUserError: User does not exist.
• 401 Invalid password or moth.utils.InvalidPasswordError: User is valid but the provided password does not match.

/validate [GET]

Validate that a token exists.
Equivalent method: validate
Takes: token
Returns valid, userid, username, permissions, expires
Error codes:

• 401 Token does not exist or moth.utils.InvalidTokenError: Token does not exist.
• 401 Token expired or moth.utils.TokenExpiredError: Token has expired.

/passvalid [GET]

Check if a password is valid without logging in.
Equivalent method: passwordValid
Takes: username, password
Returns: valid
Error codes:

• 401 Unknown username or moth.utils.NoUserError: User does not exist.

/logout [DELETE]

Delete an access token.
Equivalent method: logout
Takes: token
Returns deleted
Error codes:

• 401 Token does not exist or moth.utils.InvalidTokenError: Token does not exist.

/new [PUT]

Create a new user.
Equivalent method: newuser
Takes: username, password, permissions
Returns: userid, username, permissions
Error codes:

• 409 User already exists or moth.utils.UserExistsError: User already exists.

/del [DELETE]

Delete an existing user.
Equivalent method: deluser
Takes: id
Returns: deleted
Error codes:

• 401 User does not exist or moth.utils.NoUserError: User does not exist.

/setpass [PATCH]

Give a user a new password.
Equivalent method: newpass
Takes: id, password
Returns: updated
Error codes:

• 401 User does not exist or moth.utils.NoUserError: User does not exist.

/setperms [PATCH]

Update a users permission string.
Equivalent method: newperms
Takes: id, permissions
Returns: updated
Error codes:

• 401 User does not exist or moth.utils.NoUserError: User does not exist.

/gettokens [GET]

Check how many tokens a user has.
Equivalent method: gettokens
Takes: id
Returns: count
Error codes:

/getusers [GET]

Retrieve a list of users.
Equivalent method: getusers
Takes:
Returns: [id, username, permissions]
Error codes:

/getuser [GET]

Retrieve information about a specific user.
Equivalent method: getuser
Takes: id
Returns: id, username, permissions
Error codes:

• 401 User does not exist or moth.utils.NoUserError: User does not exist.

/deltokens [DELETE]

Clear all tokens associated with a user.
Equivalent method: deltokens
Takes: id
Returns: deleted, count
Error codes:

Important note about intended server usage

This server is intended to be entirely backend, and does not do any credential validation before performing actions. It should never be accessible to untrusted programs, and programs intending to use MOTH should perform their own checks before passing the operation over to MOTH.