diff --git a/TODO.txt b/TODO.txt index b2636f6..a7b14cb 100644 --- a/TODO.txt +++ b/TODO.txt @@ -28,7 +28,7 @@ Milestone: v0.2.0 [x] Document MemoryHexDump() [x] Document DbExists() [ ] Document UserInteractiveAuth (move docs from Matrix) -[ ] Document User +[x] Document User [ ] Move docs from Matrix to User for UserValidate [ ] Document Str and remove old functions from Util docs. diff --git a/man/man3/User.3 b/man/man3/User.3 index d8f5013..b7b45ac 100644 --- a/man/man3/User.3 +++ b/man/man3/User.3 @@ -1,4 +1,4 @@ -.Dd $Mdocdate: February 12 2023 $ +.Dd $Mdocdate: February 14 2023 $ .Dt USER 3 .Os Telodendria Project .Sh NAME @@ -65,7 +65,59 @@ under the hood. .Pp .Fn UserAuthenticate takes an access token, figures out what user it belongs to, and returns the -reference to that user. +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. .Sh RETURN VALUES +.Pp +.Fn UserValidate , +.Fn UserHistoricalValidate , +.Fn UserExists , +.Fn UserUnlock , +and +.Fn UserCheckPassword +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, which is defined as follows: +.Bd -literal -offset indent +typedef struct UserLoginInfo +{ + char *accessToken; + char *refreshToken; + char *deviceId; + long tokenLifetime; +} UserLoginInfo; +.Ed +.Pp +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. .Sh SEE ALSO .Xr Db 3