Document user interactive authentication function

man/man3/Matrix.3

@@ -1,4 +1,4 @@
-.Dd $Mdocdate: December 12 2022 $
+.Dd $Mdocdate: December 16 2022 $
 .Dt MATRIX 3
 .Os Telodendria Project
 .Sh NAME
@@ -10,6 +10,8 @@
 .Fn MatrixHttpHandler "HttpServerContext *" "void *"
 .Ft void
 .Fn MatrixErrorCreate "MatrixError"
+.Ft HashMap *
+.Fn MatrixUserInteractiveAuth "HttpServerContext *" "Db *" "HashMap *"
 .Sh DESCRIPTION
 .Nm
 provides some helper functions that bind to the
@@ -77,11 +79,26 @@ typedef enum MatrixError
 	M_CANNOT_LEAVE_SERVER_NOTICE_ROOM
 } MatrixError;
 .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
 .Pp
 .Fn MatrixErrorCreate
 returns a JSON object that represents the given error code. It can be
 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
 .Xr HttpServer 3 ,
 .Xr Log 3 ,

man/man7/telodendria-changelog.7

@@ -1,4 +1,4 @@
-.Dd $Mdocdate: December 15 2022 $
+.Dd $Mdocdate: December 16 2022 $
 .Dt TELODENDRIA-CHANGELOG 7
 .Os Telodendria Project
 .Sh NAME
@@ -32,11 +32,14 @@ as well, so you can discuss your progress and ask questions.
 .Pp
 Not released yet.
 .Pp
-Changes:
+New:
 .Bl -bullet
 .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
 Added a way to safely delete objects from the database.
 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
 the current timestamp and the thread ID, so it should be
 fairly random.
+.El
+.Pp
+Changes:
+.Bl -bullet
+.It
+Improved HTTP request logging by removing unnecessary
+log entries and making errors more specific.
 .It
 Leaked memory is now hexdump-ed out to the log if the log
 level is set to debug. This greatly simplifies debugging,