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.

confirm-code-query

confirm-token-query

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.

decrease-attempts-query

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).

gen-token

(gen-token)

Generates random confirmation token. Returns a string.

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.

registration-confirmation-query

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).

report-errors-code-query

report-errors-id-query

report-errors-simple-id-query

report-errors-token-query

retry-email

(retry-email udata)(retry-email db id)(retry-email db id reason)

retry-phone

(retry-phone udata)(retry-phone db id)(retry-phone db id reason)

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)

verify-bad-code-set

verify-bad-id-set

verify-bad-token-set