Mirage.Accounts.UserToken (mirage v0.76.0)

Module for Token functions, like building session or email tokens

Link to this section Summary

Functions

Builds a token and its hash to be delivered to the user's email.

Generates a UserToken structure that represents a user-token returned from the oauth-server of a mastodon instance

Generates a token that will be stored in a signed place, such as session or cookie. As they are signed, those tokens do not need to be hashed.

Returns the token struct for the given token value and context.

Gets all tokens for the given user for the given contexts.

Checks if the token is valid and returns its underlying lookup query.

Checks if the token is valid and returns its underlying lookup query.

Checks if the token is valid and returns its underlying lookup query.

Link to this section Functions

Link to this function

build_email_token(user, context)

Builds a token and its hash to be delivered to the user's email.

The non-hashed token is sent to the user email while the hashed part is stored in the database. The original token cannot be reconstructed, which means anyone with read-only access to the database cannot directly use the token in the application to gain access. Furthermore, if the user changes their email in the system, the tokens sent to the previous email are no longer valid.

Users can easily adapt the existing code to provide other types of delivery methods, for example, by phone numbers.

Link to this function

build_mastodon_user_token(user, token)

Generates a UserToken structure that represents a user-token returned from the oauth-server of a mastodon instance

Link to this function

build_session_token(user)

Generates a token that will be stored in a signed place, such as session or cookie. As they are signed, those tokens do not need to be hashed.

The reason why we store session tokens in the database, even though Phoenix already provides a session cookie, is because Phoenix' default session cookies are not persisted, they are simply signed and potentially encrypted. This means they are valid indefinitely, unless you change the signing/encryption salt.

Therefore, storing them allows individual user sessions to be expired. The token system can also be extended to store additional data, such as the device used for logging in. You could then use this information to display all valid sessions and devices in the UI and allow users to explicitly expire any session they deem invalid.

Link to this function

mastodon_user_tokens_query(user)

Link to this function

token_and_context_query(token, context)

Returns the token struct for the given token value and context.

Link to this function

user_and_contexts_query(user, contexts)

Gets all tokens for the given user for the given contexts.

Link to this function

verify_change_email_token_query(token, context)

Checks if the token is valid and returns its underlying lookup query.

The query returns the user found by the token, if any.

This is used to validate requests to change the user email. It is different from verify_email_token_query/2 precisely because verify_email_token_query/2 validates the email has not changed, which is the starting point by this function.

The given token is valid if it matches its hashed counterpart in the database and if it has not expired (after @change_email_validity_in_days). The context must always start with "change:".

Link to this function

verify_email_token_query(token, context)

Checks if the token is valid and returns its underlying lookup query.

The query returns the user found by the token, if any.

The given token is valid if it matches its hashed counterpart in the database and the user email has not changed. This function also checks if the token is being used within a certain period, depending on the context. The default contexts supported by this function are either "confirm", for account confirmation emails, and "reset_password", for resetting the password. For verifying requests to change the email, see verify_change_email_token_query/2.

Link to this function

verify_session_token_query(token)

Checks if the token is valid and returns its underlying lookup query.

The query returns the user found by the token, if any.

The token is valid if it matches the value in the database and it has not expired (after @session_validity_in_days).