Email authentication module

Module to verify user email by sending the user a link.The functions in the module can be implemented manually in a web server, but the recommended way is simply to use the API.

API

Examples

• see publisher/view/auth_controllers

fn new(config AuthenticatorConfig) !Authenticator

fn new_controller(params ControllerParams) Controller

fn new_database_backend(config DatabaseBackendConfig) !DatabaseBackend

factory for

fn new_stateless_authenticator(authenticator StatelessAuthenticator) !StatelessAuthenticator

fn (auth DatabaseBackend) create_auth_session(session_ AuthSession) !

fn (auth DatabaseBackend) read_auth_session(email string) ?AuthSession

fn (auth DatabaseBackend) update_auth_session(session AuthSession) !

fn (auth DatabaseBackend) set_session_authenticated(email string) !

fn (auth DatabaseBackend) delete_auth_session(email string) !

struct AttemptResult {
pub:
	authenticated bool
	attempts_left int
	time_left     time.Time
}

result of an authentication attempt returns time and attempts remaining

struct AuthAttempt {
pub:
	ip      string
	address string
	cypher  string
}

struct AuthSession {
pub mut:
	email         string
	timeout       time.Time
	auth_code     string // hex representation of 64 bytes
	attempts_left int = 3
	authenticated bool
}

Is initialized when an auth link is sent Represents the state of the authentication session

struct AuthenticationAttempt {
pub:
	email      string
	expiration time.Time
	signature  string
}

struct AuthenticationMail {
pub:
	to       string // email address being authentcated
	from     string = 'email_authenticator@crystallib.tf'
	subject  string = 'Verify your email'
	body     string = 'Please verify your email by clicking the link below'
	callback string // callback url of authentication link
}

struct Authenticator {
	secret string
mut:
	config  SmtpConfig @[required]
	backend IBackend // Backend for authenticator
}

Creates and updates, authenticates email authentication sessions

fn (mut auth Authenticator) email_authentication(config SendMailConfig) !

fn (mut auth Authenticator) send_verification_mail(config SendMailConfig) !

sends mail with verification link

fn (mut auth Authenticator) send_login_link(config SendMailConfig) !

sends mail with login link

fn (mut auth Authenticator) authenticate_login_attempt(attempt LoginAttempt) !

sends mail with login link

fn (mut auth Authenticator) authenticate(email string, cypher string) !

authenticates if email/cypher combo correct within timeout and remaining attemts

Todo: address based request limits recognition to prevent brute

Todo: max allowed request per seccond to prevent dos

fn (mut auth Authenticator) await_authentication(params AwaitAuthParams) !

function to check if an email is authenticated

fn (mut auth Authenticator) is_authenticated(email string) !bool

function to check if an email is authenticated

struct AuthenticatorConfig {
	secret  string
	smtp    SmtpConfig
	backend IBackend
}

struct AwaitAuthParams {
	email   string @[required]
	timeout time.Duration = 3 * time.minute
}

struct Controller {
	vweb.Context
	callback string @[vweb_global]
mut:
	authenticator Authenticator @[vweb_global]
}

email authentication controller that be be added to vweb projects

fn (mut app Controller) send_verification_mail() !vweb.Result

route responsible for verifying email, email form should be posted here

fn (mut app Controller) is_verified() vweb.Result

route responsible for verifying email, email form should be posted here

fn (mut app Controller) email_authentication() vweb.Result

route responsible for verifying email, email form should be posted here

fn (mut app Controller) verify() vweb.Result

route responsible for verifying email, email form should be posted here

fn (mut app Controller) authenticate() !vweb.Result

fn (mut app Controller) authentication_link(address string, cypher string) !vweb.Result

struct ControllerParams {
	logger        &log.Logger
	authenticator Authenticator @[required]
}

struct DatabaseBackendConfig {
	db_path string = 'email_authenticator.sqlite'
}

struct EmailClient {
	url string @[required]
}

session controller that be be added to vweb projects

fn (client EmailClient) email_authentication(params SendMailConfig) !

verify_email posts an email verification req to the email auth controller

fn (client EmailClient) is_verified(address string) !bool

verify_email posts an email verification req to the email auth controller

fn (client EmailClient) send_verification_email(params SendMailConfig) !

send_verification_email posts an email verification req to the email auth controller

fn (c EmailClient) authenticate(address string, cypher string) !AttemptResult

authenticate posts an authentication attempt req to the email auth controller

struct LoginAttempt {
pub:
	email      string
	expiration time.Time
	signature  string
}

struct SendMailConfig {
	email string
	mail  VerificationMail
	link  string
}

struct SmtpConfig {
	server   string
	from     string
	port     int
	username string
	password string
}

struct StatelessAuthenticator {
pub:
	secret string
pub mut:
	mail_client MailClient
}

fn (mut a StatelessAuthenticator) send_authentication_mail(mail AuthenticationMail) !

fn (auth StatelessAuthenticator) authenticate(attempt AuthenticationAttempt) !

sends mail with login link

struct VerificationMail {
pub:
	from    string = 'email_authenticator@spiderlib.ff'
	subject string = 'Verify your email'
	body    string = 'Please verify your email by clicking the link below'
}