Document user interactive authentication function

This commit is contained in:
Jordan Bancino 2022-12-16 20:52:55 +00:00
parent fb06d17b16
commit 9a31b1f350
2 changed files with 32 additions and 5 deletions

View file

@ -1,4 +1,4 @@
.Dd $Mdocdate: December 12 2022 $ .Dd $Mdocdate: December 16 2022 $
.Dt MATRIX 3 .Dt MATRIX 3
.Os Telodendria Project .Os Telodendria Project
.Sh NAME .Sh NAME
@ -10,6 +10,8 @@
.Fn MatrixHttpHandler "HttpServerContext *" "void *" .Fn MatrixHttpHandler "HttpServerContext *" "void *"
.Ft void .Ft void
.Fn MatrixErrorCreate "MatrixError" .Fn MatrixErrorCreate "MatrixError"
.Ft HashMap *
.Fn MatrixUserInteractiveAuth "HttpServerContext *" "Db *" "HashMap *"
.Sh DESCRIPTION .Sh DESCRIPTION
.Nm .Nm
provides some helper functions that bind to the provides some helper functions that bind to the
@ -77,11 +79,26 @@ typedef enum MatrixError
M_CANNOT_LEAVE_SERVER_NOTICE_ROOM M_CANNOT_LEAVE_SERVER_NOTICE_ROOM
} MatrixError; } MatrixError;
.Ed .Ed
.Pp
.Fn MatrixUserInteractiveAuth
executes the user interactive authentication flow. A number of Matrix
client API requests require this flow, so this function provides a
convenient abstraction. Currently, it only implements a single-stage
"m.login.dummy" auth, so it's more of a formality than anything else,
but in the future, this function may support more authentication
flows.
.Sh RETURN VALUES .Sh RETURN VALUES
.Pp .Pp
.Fn MatrixErrorCreate .Fn MatrixErrorCreate
returns a JSON object that represents the given error code. It can be returns a JSON object that represents the given error code. It can be
immediately returned as the HTTP response body, or modified as needed. immediately returned as the HTTP response body, or modified as needed.
.Pp
.Fn MatrixUserInteractiveAuth
returns NULL when the auth is successful. That is, if it returns NULL,
then the caller can proceed assuming that the client has done all the
right things to authenticate itself. If this function does not return
NULL, then the returned JSON object should be passed along to the
client immediately without continuing.
.Sh SEE ALSO .Sh SEE ALSO
.Xr HttpServer 3 , .Xr HttpServer 3 ,
.Xr Log 3 , .Xr Log 3 ,

View file

@ -1,4 +1,4 @@
.Dd $Mdocdate: December 15 2022 $ .Dd $Mdocdate: December 16 2022 $
.Dt TELODENDRIA-CHANGELOG 7 .Dt TELODENDRIA-CHANGELOG 7
.Os Telodendria Project .Os Telodendria Project
.Sh NAME .Sh NAME
@ -32,11 +32,14 @@ as well, so you can discuss your progress and ask questions.
.Pp .Pp
Not released yet. Not released yet.
.Pp .Pp
Changes: New:
.Bl -bullet .Bl -bullet
.It .It
Improved HTTP request logging by removing unnecessary Added a basic form of the user interactive authentication API,
log entries and making errors more specific. which can be used by any endpoints that the spec says require
it. Currently, it only implements a single dummy login flow,
so it's more of a fomality than anything else, but more login
flows can easily be added in the future.
.It .It
Added a way to safely delete objects from the database. Added a way to safely delete objects from the database.
While the database is for persistent storage, there may While the database is for persistent storage, there may
@ -49,6 +52,13 @@ be used extensively for generating session tokens, device
IDs, access tokens, and more. This generator is seeded by IDs, access tokens, and more. This generator is seeded by
the current timestamp and the thread ID, so it should be the current timestamp and the thread ID, so it should be
fairly random. fairly random.
.El
.Pp
Changes:
.Bl -bullet
.It
Improved HTTP request logging by removing unnecessary
log entries and making errors more specific.
.It .It
Leaked memory is now hexdump-ed out to the log if the log Leaked memory is now hexdump-ed out to the log if the log
level is set to debug. This greatly simplifies debugging, level is set to debug. This greatly simplifies debugging,