.Dd $Mdocdate: March 6 2023 $
.Dt USER 3
.Os Telodendria Project
.Sh NAME
.Nm User
.Nd Convenience functions for working with local users.
.Sh SYNOPSIS
.In User.h
.Ft int
.Fn UserValidate "char *" "char *"
.Ft int
.Fn UserHistoricalValidate "char *" "char *"
.Ft int
.Fn UserExists "Db *" "char *"
.Ft User *
.Fn UserCreate "Db *" "char *" "char *"
.Ft User *
.Fn UserLock "Db *" "char *"
.Ft User *
.Fn UserAuthenticate "Db *" "char *"
.Ft int
.Fn UserUnlock "User *"
.Ft UserLoginInfo *
.Fn UserLogin "User *" "char *" "char *" "char *" "int"
.Ft char *
.Fn UserGetName "User *"
.Ft int
.Fn UserCheckPassword "User *" "char *"
.Ft int
.Fn UserSetPassword "User *" "char *"
.Ft int
.Fn UserDeactivate "User *"
.Ft HashMap *
.Fn UserGetDevices "User *"
.Ft UserAccessToken *
.Fn UserGenerateAccessToken "User *" "char *" "int"
.Ft int
.Fn UserAccessTokenSave "Db *" "UserAccessToken *"
.Ft void
.Fn UserAccessTokenFree "UserAccessToken *"
.Ft int
.Fn UserDeleteToken "User *" "char *"
.Ft int
.Fn UserDeleteTokens "User *"
.Ft UserId *
.Fn UserIdParse "char *" "char *"
.Ft void
.Fn UserIdFree "UserId *"
.Sh DESCRIPTION
The
.Nm
API provides a wrapper over the database and offers an easy way for managing
local users. It supports all of the locking mechanisms that the database does,
and provides features for authenticating local users, among other tasks.
.Pp
.Bd -literal -offset indent
typedef struct UserLoginInfo
{
    UserAccessToken *accessToken;
    char *refreshToken;
} UserLoginInfo;

typedef struct UserAccessToken
{
    char *user;
    char *string;
    char *deviceId;
    long lifetime;
} UserAccessToken;

typedef struct UserId
{
    char *localpart;
    char *server;
} UserId;
.Ed
.Pp
.Fn UserValidate
takes a localpart and domain as separate parameters and validates it against the
rules of the Matrix specification. The reason the domain is required is because
the spec imposes limitations on the length of the user name, and the longer the
domain name is, the shorter the local part can be. This function is used to
ensure that client-provided localparts are valid on this server.
.Fn UserHistoricalValidate
is called the exact same way, except it is a little more lenient. It is used to
validate user parts on other servers, since some usernames might exist that are
not fully spec compliant, but remain in use due to historical reasons.
.Pp
.Fn UserExists
takes a localpart and checks whether or not it exists in the database.
.Pp
.Fn UserCreate
creates a new user. It takes a localpart, which is assumed to be valid, and
a password.
.Pp
.Fn UserLock
takes a localpart and obtains a database reference to the user represented by that
localpart. It behaves analogously to
.Fn DbLock ,
and in fact uses it under the hood to ensure that the user can only be modified
by the thread that has locked the user.
.Fn UserUnlock
returns the user reference back to the database. It uses
.Fn DbUnlock
under the hood.
.Pp
.Fn UserAuthenticate
takes an access token, figures out what user it belongs to, and returns the
reference to that user. This function should be used by most endpoints that
require valid user authentication, since most endpoints are authenticated via
access tokens.
.Pp
.Fn UserLogin
is used for logging in a user. It takes the user's password, device ID, device
display name, and a boolean value indicating whether or not the client supports
refresh tokens. This function logs in the user and generates an access token to be
returned to the client.
.Pp
.Fn UserGetName
gets the name attached to a user object. It can be used for the few cases where
it's necessary to know the localpart of a user.
.Pp
.Fn UserCheckPassword
takes a password and verifies it against a user object. Telodendria does not
store passwords in plain text, so this function hashes the password and and
checks it against what's stored in the database.
.Pp
.Fn UserSetPassword
resets the given user's password by hashing a plain text password and
storing it in the database.
.Pp
.Fn UserDeactivate
deactivates a user such that it can no longer be used to log in, but
the username is still taken. This is to prevent future users from
pretending to be previous users of a given localpart.
.Pp
.Fn UserGetDevices
fetches the devices that belong to the user, in JSON format,
identical to what's stored in the database. In fact, this JSON is
still linked to the database, so it should not be freed with
.Fn JsonFree .
.Pp
.Fn UserAccessTokenGenerate ,
.Fn UserAccessTokenSave ,
and
.Fn UserAccessTokenFree
are used for managing individual access tokens on a user. They
operate on the UserAccessToken structure.
.Fn UserAccessTokenGenerate
takes the user localpart to generate the token for, the device ID,
for the token, and a boolean value indicating whether or not the token
should expire.
.Fn UserAccessTokenSave
writes the access token to the database.
.Pp
.Fn UserDeleteToken
and
.Fn UserDeleteTokens
delete a specific access token/refresh token pair, or all the access
and refresh tokens for a given user, respectively.
.Pp
.Fn UserIdParse
parses either a localpart or a fully-qualified Matrix ID.
.Fn UserIdFree
frees the result of this parsing.
.Sh RETURN VALUES
.Pp
.Fn UserValidate ,
.Fn UserHistoricalValidate ,
.Fn UserExists ,
.Fn UserUnlock ,
.Fn UserCheckPassword ,
.Fn UserSetPassword ,
.Fn UserDeactivate ,
.Fn UserAccessTokenSave ,
.Fn UserDeleteToken ,
and
.Fn UserDeleteTokens
all return a boolean value. Non-zero values indicate success, and zero values
indicate failure.
.Pp
.Fn UserCreate ,
.Fn UserLock ,
and
.Fn UserAuthenticate
return a pointer to a User, or NULL if an error occurred.
.Pp
.Fn UserGetName
returns a pointer to the string that holds the localpart of the user represented
by the given user pointer. This pointer should not be freed by the caller , as it
is used internally and will be freed when the user is unlocked.
.Pp
.Fn UserLogin
returns a UserLoginInfo struct, or
.Dv NULL
if something goes wrong.
All this information should be returned to the client that is logging in. If the
client doesn't support refresh tokens, then refreshToken will be NULL.
.Pp
.Fn UserGetDevices
returns a JSON object that is linked to the database, or NULL if
there was an error. The result should not be freed with
.Fn JsonFree
because it is still directly attached to the database. This object
is an exact representation of what is stored on the disk.
.Pp
.Fn UserAccessTokenGenerate
generates an access token structure that should be freed when it is
no longer needed, or
.Dv NULL
if there was a memory error.
.Pp
.Fn UserIdParse
returns a UserId structure that should be freed when it is no longer
needed, or
.Dv NULL
if there was a memory error.
.Sh SEE ALSO
.Xr Db 3