Document Uia API.

TODO.txt

@@ -22,11 +22,11 @@ Milestone: v0.2.0
 [x] User login
     [x] Logout all
 
-[~] Documentation
+[x] Documentation
     [x] User functions
     [x] Json functions
     [x] Db functions
-    [ ] Uia (move docs from Matrix)
+    [x] Uia (move docs from Matrix)
 
 [x] Convert proposals to man pages
 

man/man3/Uia.3

@@ -0,0 +1,123 @@
+.Dd $Mdocdate: March 7 2023 $
+.Dt UIA 3
+.Os Telodendria Project
+.Sh NAME
+.Nm Uia
+.Nd User Interactive Authentication API.
+.Sh SYNOPSIS
+.In Uia.h
+.Ft UiaStage *
+.Fn UiaStageBuild "char *" "HashMap *"
+.Ft Array *
+.Fn UiaDummyFlow "void"
+.Ft void
+.Fn UiaCleanup "MatrixHttpHandlerArgs *"
+.Ft int
+.Fn UiaComplete "Array *" "HttpServerContext *" "Db *" "HashMap *" "HashMap **" "TelodendriaConfig *"
+.Ft void
+.Fn UiaFlowsFree "Array *"
+.Sh DESCRIPTION
+.Nm
+takes care of all the logic for performing user interactive
+authentication as defined by the Matrix specification. API endpoints
+that require authentication via user interactive authentication
+build up flows and any necessary parameters, and pass them into
+.Fn UiaComplete ,
+which validates
+.Dv auth
+objects and maintains session state to track the progress of a
+client through the user interactive authentication flows. The idea
+is that an API endpoint will not progress until user interactive
+authentication has succeeded.
+.Nm
+makes it easy for the numerous API endpoints that utilize this
+authentication mechanism to implement it.
+.Pp
+.Fn UiaStageBuild
+builds a single stage. A stage consists of a string identifying its
+type, which is used to instruct the client as to what should be
+done, and parameters, which is a JSON object that contains
+implementation-specific parameters for completing the stage. This
+function takes those two parameters in that order.
+.Pp
+.Fn UiaDummyFlow
+builds a flow that consists only of a dummy stage. This is useful
+when an endpoint is required to use user interactive authentication,
+but doesn't actually want to require the user to do anything. Since
+the dummy flow is a pretty common flow, it seemed sensible to have
+a function for it. Other flows are built by the caller that wishes
+to perform user interactive authentication.
+.Pp
+.Fn UiaCleanup
+should be called periodically to purge old sessions. Session are
+only valid for a few minutes after their last access. After that, they
+should be purged so the database doesn't fill up with session files.
+This function is specifically designed to be called via
+.Xr Cron 3 .
+.Pp
+.Fn UiaComplete
+does the bulk of the work for user interactive authentication. It
+takes many paramters:
+.Bl -bullet
+.It
+An array of arrays of stages. Stages should be created with
+.Fn UiaStageBuild ,
+and then put into an array to create a flow. Those flows should then
+be put into an array and passed as this paramter. Do note that
+because of the loose typing of Telodendria's Array API, it is very
+easy to make mistakes here; if you are implementing a new route that
+requires user interactive authentication, then refer to an existing
+route so you can see how it works.
+.It
+An HTTP server context. This is required to set the response headers
+in the event of an error.
+.It
+The database where user interactive authentication sessons are
+persisted.
+.It
+The JSON request body that contains the client's
+.Dv auth
+object, which will be read, parsed, and handled as appropriate.
+.It
+A pointer to a pointer where a JSON response can be placed if
+necessary. If
+.Fn UiaComplete
+encounters a client error, such as a failure to authenticate, or
+outstanding stages that have not been completed, it will place a
+JSON response here that is expected to be returned to the client.
+This response will include a description of all the flows, stages,
+and their parameters.
+.It
+A valid Telodendria configuration structure, because a few values
+are read from the configuration during certain stages of the
+authentication.
+.El
+.Pp
+.Fn UiaFlowsFree
+frees an array of flows, as described above. Even though the
+caller constructs this array, it is convenient to free it in its
+entirety in a single function call.
+.Sh RETURN VALUES
+.Pp
+.Fn UiaStageBuild
+returns an opaque structure that represents a user interactive
+authentication stage, and any parameters the client needs to complete
+it. It may return NULL if there is an error allocating memory.
+.Pp
+.Fn UiaDummyFlow
+returns an array that represents a dummy authentication flow, or
+NULL if it could not allocate memory for it.
+.Pp
+.Fn UiaComplete
+returns an integer less than zero if it experiences an internal
+failure, such as a failure to allocate memory, or a corrupted
+database. It returns 0 if the client has remaining stages to
+complete. In this case, it will have set the response headers
+and the passed response pointer, so the caller should immediately
+return the response to the client. This function returns 1 if the
+user has successfully completed all stages. Only in this case shall
+the caller proceed with its logic.
+.Sh SEE ALSO
+.Xr User 3 ,
+.Xr Db 3 ,
+.Xr Cron 3

src/Uia.c

@@ -181,13 +181,13 @@ UiaDummyFlow(void)
         return NULL;
     }
 
-    ArrayAdd(response, UiaBuildStage("m.login.dummy", NULL));
+    ArrayAdd(response, UiaStageBuild("m.login.dummy", NULL));
 
     return response;
 }
 
 UiaStage *
-UiaBuildStage(char *type, HashMap * params)
+UiaStageBuild(char *type, HashMap * params)
 {
     UiaStage *stage = Malloc(sizeof(UiaStage));
 

src/include/Uia.h

@@ -32,7 +32,7 @@
 typedef struct UiaStage UiaStage;
 
 extern UiaStage *
- UiaBuildStage(char *, HashMap *);
+ UiaStageBuild(char *, HashMap *);
 
 extern Array *
  UiaDummyFlow(void);