How Hubs Client Logs in Users

[Voxelghiest]

This ticket documents how Hubs Client authenticates and signs in its user accounts as part of the research for #56.

[Voxelghiest]

Hubs Client Login Pipeline

I searched through the Hubs Client and Reticulum code and traced the lifecycle of a user authentication request. Because there are so many different portions of the codebase involved in this, I've labelled each step with a link to the corresponding script file or code block. Furthermore, these steps are broken into chunks depending on which part of the Hubs system handles that portion of the process.

Hubs Client

• signin.js: Anytime a user needs to be authenticated, they are directed to the /signin page of Hubs Client's website.
• SignInModalContainer.submitEmail: The /signin page contains a SignInModalContainer component that prompts the user for their login email address. When the user enters their email, the submitEmail function of the SignInModalContainer is called.
• AuthContext.signIn: submitEmail uses an AuthContext object to handle the sign-in process, passing the email address to the function AuthContext.signIn. A context object, like AuthContext, is a special kind of object in React that is used to share data between different UI components.
• AuthChannel.startAuthentication: AuthContext.signIn creates an AuthChannel object to communicate with Reticulum. Each AuthChannel object is associated with a single Socket, which is a connection to the Reticulum server. AuthContext.signIn calls the function AuthChannel.startAuthentication, which takes the user's email and pushes an "auth_request" event to the Reticulum server.

Reticulum

• AuthChannel.handle_in/3: Reticulum has its own AuthChannel class that intercepts any authentication requests made to the server. Each instance of the function AuthChannel.handle_in responds to a specific kind of authentication request. The "auth_request" version of handle_in does all of the following:
  • [LoginToken.new_login_token_for_email/1](): Creates a LoginToken object to hold the login request as open until the user verifies their email. This object has a token, which is a random hexadecimal value.
  • Encrypts the email address as auth_payload and uses the token from the LoginToken created earlier as auth_token. Two other values, auth_topic and auth_origin, are also created.
  • Email.auth_email/2: Sends an email to the user asking for verification, with a link that contains the four auth_ values mentioned above and redirects the user to the Hubs Client home page.

Hubs Client (Again)

• HomePage.js: When the Hubs Client home page loads, it recognizes the auth_topic value in the link and redirects the user to /verify instead.
• verify.js: This page is analogous to the /signin page from before.
• VerifyModalContainer.useVerify: The /verify page contains a VerifyModalContainer component. This component has a useVerify function that is called when the component is created.
• AuthContext.verify: Again, the AuthContext object is used, this time with a different function verify. verify is passed the four auth_ values from before.
• AuthChannel.verifyAuthentication: A new AuthChannel is created for the verification step, and the function AuthChannel.verifyAuthentication is called, passing in the auth_ values. After opening up a new socket channel to Reticulum, verifyAuthentication does two things:
  • Sets itself up to respond to future "auth_credentials" events broadcast on the socket it opened (more on this later)
  • Sends an "auth_verified" message to Reticulum over the socket, passing it the auth_token and auth_payload values

Reticulum (Again)

• AuthChannel.handle_in/3: As before, Reticulum's AuthChannel has a different handle_in function for handling "auth_verified" messages. This version of handle_in does the following:
  • Uses the auth_token value to confirm that a matching LoginToken exists in the database (recall that a LoginToken represents an open verification request)
  • Decrypts the auth_payload back into the original email address of the user
  • Sends an "auth_credentials" message back along the socket that sent the "auth_verified" message, containing the decrypted email and a new kind of token that exists for the lifetime of the user's session (for those curious about this new token, see Reticulum's Guardian module)

Hubs Client (Again Again)

• AuthChannel.handleAuthCredentials: Recall that before sending Reticulum the "auth_verified" message, Hubs Client started listening for "auth_credentials" messages on the same socket. Now, the "auth_credentials" message sent by Reticulum is received and passed to AuthChannel.handleAuthCredentials. This function updates the AuthContext object with the user's email and the new token Reticulum created, and then, finally, the user is signed in to Hubs Client.