.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