amelinium.model.confirmation
added in 1.0.0
amelinium service, confirmation model.
code-to-token
(code-to-token db id code)
Returns a confirmation token associated with the given confirmation code and identity. Additionally, returns confirmation status.
create
(create db id user-id exp attempts user-required? reason)
(create db id user-id exp attempts id-type user-required? reason)
Creates a confirmation code for an existing user identified by the given user ID (user-id
). The identity to be confirmed (id
) can be an e-mail address (:email
), a phone number (:phone
) or any supported value.
When the confirmation was already generated and it hasn’t expired, it is returned with an existing code and token.
When the given e-mail is already assigned to some other registered user the returned map will contain 4 keys: :exists?
set to true
, :existing-user/id
set to ID of existing user, :id
set to the given e-mail (as a string) and :reason
set to the given reason (as a keyword, or nil
if not given).
Attempts counter is increased each time this function is called.
create-for-change
(create-for-change db id user-id exp attempts)
(create-for-change db id user-id exp attempts id-type)
Creates a confirmation code for an existing user identified by the given user ID (user-id
). The identity to be confirmed (id
) can be an e-mail address (:email
), a phone number (:phone
) or any supported value.
When the confirmation was already generated and it hasn’t expired, it is returned with an existing code and token.
When the given e-mail is already assigned to some other registered user the returned map will contain 4 keys: :exists?
set to true
, :existing-user/id
set to ID of existing user, :id
set to the given e-mail (as a string) and :reason
set to the given reason (as a keyword, or nil
if not given).
Attempts counter is increased each time this function is called.
create-for-recovery
(create-for-recovery db id user-id exp attempts)
(create-for-recovery db id user-id exp attempts id-type)
Creates a recovery code for an existing user identified by the given user ID (user-id
). The identity to be confirmed (id
) can be an e-mail address (:email
), a phone number (:phone
) or any supported value.
When the confirmation was already generated and it hasn’t expired, it is returned with an existing code and token.
When the given e-mail is assigned to the given user the returned map will contain 4 keys: :exists?
set to true
, :existing-user/id
set to ID of existing user, :id
set to the given e-mail (as a string) and :reason
set to the given reason (as a keyword, or nil
if not given).
Attempts counter is increased each time this function is called.
create-for-registration
(create-for-registration udata)
(create-for-registration db udata)
(create-for-registration db udata reason)
Creates a confirmation code for a new user identified by the given e-mail address.
When the confirmation was already generated and it hasn’t expired, it is returned with an existing code and token.
When the given e-mail is already assigned to a registered user the returned map will contain 4 keys: :exists?
set to true
, :existing-user/id
set to ID of existing user, :id
set to the given e-mail (as a string) and :reason
set to the given reason (as a keyword, or nil
if not given).
Attempts counter is increased each time this function is called.
delete
(delete db id)
(delete db id reason)
Deletes confirmation of identity id
from a database.
establish
(establish db id code exp-minutes reason)
(establish db id code token exp-minutes reason)
(establish db token exp-minutes reason)
Confirms an identity (id
), which may be an e-mail or a phone number, using a token or an identifier with a code. If the verification is successful, sets confirmed
flag to TRUE
(1) in a database which prevents from further confirmations and marks identity as confirmed for other operations. The exp-minutes
argument should be a positive integer and will be used to increase expiration time by the given amount of minutes. This is to ensure that the next operation, if any, which may take some time, will succeed. The reason
argument is the confirmation reason and should match the reason given during the generation of a token or code.
Returns a map with :confirmed?
set to true
if the given token or code was verified. Returns a map with :confirmed?
set to false
and :error
set to a keyword describing the cause if the token or code was not verified. Returns nil
if something went wrong during the interaction with a database or when the required input parameters were empty.
The :user/id
key of a result, if exists, contains numeric user identifier of a requester (the user for whom the verification was initiated).
If the identity is already confirmed and there is no error (i.e. confirmation has not yet expired), it will also return a map with :confirmed?
set to true
.
gen-code
(gen-code)
Generates pseudo-random, 7-digits confirmation code. Returns a number.
gen-confirmation-query
(gen-confirmation-query identity-type user-required?)
Generates a confirmation query for an e-mail or a phone UPDATED by an existing user or used in other process (like password recovery).
Note: it may return a query giving an empty result set if there is no requesting user in a database.
gen-full-confirmation-query
(gen-full-confirmation-query identity-type)
Generates a confirmation query for an e-mail or a phone used during registration of a NEW USER account.
gen-report-errors-query
(gen-report-errors-query where)
Generates SQL query for reporting errors found during confirmation process. When executed the query returns a map with boolean values and the following keys: :confirmed
(already confirmed), :attempts
(attempts exceeded), :reason
(reason for the given token or code is different from the reason for which the confirmation had been created for), :expires
(confirmation expired), :present
(an e-mail or a phone number is already assigned to an existing user).
make-qtoken
(make-qtoken x)
(make-qtoken x y)
(make-qtoken x y z)
(make-qtoken x y z & more)
Generates a quick token on a basis of a string representation of the given argument(s). Returns a string.
make-qtoken-all
(make-qtoken-all x)
(make-qtoken-all x y)
(make-qtoken-all x y z)
(make-qtoken-all x y z & more)
Generates a quick token on a basis of a string representation of the given argument(s) which all must not be an empty strings nor nil
values. Returns a string or nil
.
make-qtoken-some
(make-qtoken-some x)
(make-qtoken-some x y)
(make-qtoken-some x y z)
(make-qtoken-some x y z & more)
Generates a quick token on a basis of a string representation of the given argument(s) which combined may not be an empty string. Returns a string or nil
.
qtoken-matches?
(qtoken-matches? qtoken)
(qtoken-matches? qtoken a)
(qtoken-matches? qtoken a b)
(qtoken-matches? qtoken a b c)
(qtoken-matches? qtoken a b c d)
(qtoken-matches? qtoken a b c d & more)
Checks if a quick token qtoken
matches the result of applying make-qtoken
to all other arguments which cannot be an empty string after concatenation. If combined arguments are empty, nil
or false
, returns false
. If qtoken
is falsy or an empty string, returns false
too. If qtoken
matches the calculated quick token, returns true
.
report-errors
(report-errors db token reason should-be-confirmed?)
(report-errors db id code reason should-be-confirmed?)
(report-errors db id token code reason should-be-confirmed?)
Returns a set of keywords indicating confirmation errors detected when querying the confirmations table. When token
is given then it will be used to match the correct data row. When id
and code
are given then they will be used to match the correct data row. When the id
is given but the code
is nil
then the matching will be performed on id
and reason
(to match on id
only and not reason
, explicitly set code to false
).
specific-id
(specific-id errs id src-id email-id phone-id)
(specific-id errs src-id dst-id)
Makes errors more specific by replacing generic bad ID error (as a keyword) with a bad e-mail or phone error.
status
(status db id qtoken)
(status db id qtoken reason)
Returns confirmation status as a map containing the following keys: :id
, :id_type
, :attempts
, :expires
, :token
, :confirmed?
and :qtoken
. The arguments should be db
(database connection object), id
(user’s identity for which the verification is required), qtoken
(quick token derived from confirmation token to authorize the operation) and optional reason
(confirmation reason). If reason is not given then all user’s confirmation for the given identity will be analyzed and their quick tokens calculated; the first quick token that matches the one passed as an argument will cause the result to be returned.
update-request-id
(update-request-id db token request-id)
(update-request-id db id code request-id)
(update-request-id db id code token request-id)