verifier

README

Verifier

Verifier package lets you verify emails & phone numbers, with customization available at different components. There's a functional (if provided with valid configurations) sample app provided here.

How does it work?

Verifier generates secrets with an expiry, appropriate for emails & mobile phones. In case of emails, it generates a 256 character long random alpha-numeric string, and a 6 character long numeric string for mobile phones.

By default, it uses AWS SES for sending e-mails & AWS SNS for sending SMS/text messages.

How to customize?

You can customize the following components of verifier.

    // Customize the default templates
    // there should be 2 string placeholders for email body. First is the 'callback URL' and 2nd is the expiry
    verifier.DefaultEmailOTPPayload = ``
    // there should be 1 string placeholder for SMS body. It will be the secret itself
    verifier.DefaultSMSOTPPayload = ``
    // ==

    vsvc, err := verifier.NewCustom(&Config{}, nil,nil,nil)
	if err != nil {
		log.Println(err)
		return
    }

    // Service provider for sending emails
    err := v.CustomEmailHandler(email)
	if err != nil {
        log.Println(err)
		return
    }
    // ==

    // Service provider for sending messages to mobile
	err = v.CustomMobileHandler(mobile)
	if err != nil {
        log.Println(err)
		return err
    }
    // ==

    // Persistent store used by verifier for storing secrets and all the requests
	err = v.CustomStore(verStore)
	if err != nil {
        log.Println(err)
		return
    }
    // ==

    // Using custom email & text message body
    verreq, err := vsvc.NewRequest(verifier.CommTypeEmail, recipient)
    if err != nil {
        log.Println(err)
        return
    }

    // callbackURL can be used inside the custom email body
    callbackURL, err := verifier.EmailCallbackURL("https://example.com", verreq.Recipient, verreq.Secret)
    if err != nil {
        log.Println(err)
        return
    }

    err = vsvc.NewEmailWithReq(verreq, "subject", "body")
    if err != nil {
        log.Println(err)
        return
    }

    err = vsvc.NewMobileWithReq(verreq, fmt.Sprintf("%s is your OTP", verreq.Secret))
    if err != nil {
        log.Println(err)
        return
    }
    // ==

TODO

1. Unit tests
2. Setup a web service, which can be independently run, and consumed via APIs

The gopher

The gopher used here was created using Gopherize.me. Verifier helps you keep those scammers and bots away just like our hacker gopher!

Documentation

Overview

Package verifier is used for validation & verification of email, sms etc.

Index

• Constants
• Variables
• func EmailCallbackURL(baseurl, email, secret string) (string, error)
• type CommStatus
• type CommType
• type Config
• type Request
• type Verifier
  • func New(cfg *Config, verStore store, email emailService, mobile mobileService) (*Verifier, error)
  • func (ver *Verifier) CustomEmailHandler(email emailService) error
  • func (ver *Verifier) CustomMobileHandler(mobile mobileService) error
  • func (ver *Verifier) CustomStore(verStore store) error
  • func (ver *Verifier) NewEmail(recipient, subject string) error
  • func (ver *Verifier) NewEmailWithReq(verreq *Request, subject, body string) error
  • func (ver *Verifier) NewMobile(recipient string) error
  • func (ver *Verifier) NewMobileWithReq(verreq *Request, body string) error
  • func (ver *Verifier) NewRequest(ctype CommType, recipient string) (*Request, error)
  • func (ver *Verifier) VerifyEmailSecret(recipient, secret string) error
  • func (ver *Verifier) VerifyMobileSecret(recipient, secret string) error

Constants

const (
	// CommTypeMobile communication type mobile
	CommTypeMobile = CommType("mobile")
	// CommTypeEmail communication type email
	CommTypeEmail = CommType("email")

	// VerStatusPending verification status pending
	VerStatusPending = verificationStatus("pending")
	// VerStatusExpired verification status expired
	VerStatusExpired = verificationStatus("expired")
	// VerStatusVerified verification status verified
	VerStatusVerified = verificationStatus("verified")
	// VerStatusRejected verification status rejected
	VerStatusRejected = verificationStatus("rejected")
	// VerStatusExceededAttempts verification status when attempts are exceeded
	VerStatusExceededAttempts = verificationStatus("exceeded-attempts")
)

Variables

var (
	// DefaultEmailOTPPayload is the default email body used
	DefaultEmailOTPPayload = `` /* 582-byte string literal not displayed */

	// DefaultSMSOTPPayload is the default text message body
	DefaultSMSOTPPayload = "%s is the OTP to verify your mobile number. It is valid only for %s."
)

var (
	// ErrMaximumAttemptsExceeded is the error returned when maximum verification attempts have exceeded
	ErrMaximumAttemptsExceeded = errors.New("maximum attempts exceeded")
	// ErrSecretExpired is the error returned when the verification secret has expired
	ErrSecretExpired = errors.New("verification secret expired")
	// ErrInvalidSecret is the error returned upon receiving invalid secret
	ErrInvalidSecret = errors.New("invalid verification secret")
	// ErrInvalidMobileNumber is the error returned upon receiving invalid mobile number
	ErrInvalidMobileNumber = errors.New("invalid mobile number provided")
	// ErrInvalidEmail is the error returned upon receiving invalid email address
	ErrInvalidEmail = errors.New("invalid email address provided")
	// ErrEmptyEmailBody is the error returned when using custom email body and it's empty
	ErrEmptyEmailBody = errors.New("empty email body")
	// ErrEmptyMobileMessageBody is the error returned when using custom mobile message body and it's empty
	ErrEmptyMobileMessageBody = errors.New("empty mobile message body")
)

Functions

func EmailCallbackURL

func EmailCallbackURL(baseurl, email, secret string) (string, error)

EmailCallbackURL adds the relevant query string parameters to the email callback URL

Types

type CommStatus

type CommStatus struct {
	Status string                 `json:"status,omitempty"`
	Data   map[string]interface{} `json:"data,omitempty"`
}

CommStatus stores the status of the communication sent

type CommType

type CommType string

CommType defines the communication type (mobile, Email)

type Config

type Config struct {
	// MaxVerifyAttempts is used to set the maximum number of times verification attempts can be made
	MaxVerifyAttempts int `json:"maxVerifyAttempts,omitempty"`
	// EmailOTPExpiry is used to define the expiry of a secret generated to verify email
	EmailOTPExpiry time.Duration `json:"emailOTPExpiry,omitempty"`
	// MobileOTPExpiry is used to define the expiry of a secret generated to verify mobile phone number
	MobileOTPExpiry time.Duration `json:"mobileOTPExpiry,omitempty"`

	// EmailCallbackURL is used to generate the callback link which is sent in the verification email
	/*
	   Two query string attributes are added to the callback URL while sending the verification link.
	   1) 'email' - The email address to which verification mail was sent
	   2) 'secret' - The secret generated for the email, this is required while verification
	*/
	EmailCallbackURL string `json:"emailCallbackURL,omitempty"`
	// DefaultFromEmail is used to set the "from" email while sending verification emails
	DefaultFromEmail string `json:"defaultFromEmail,omitempty"`
	// DefaultEmailSub is the email subject set while sending verification emails
	/*
	   If not set, a hardcoded string "Email verification request" is set as the subject.
	   The default subject is used if no subject is sent while calling the Send function
	*/
	DefaultEmailSub string `json:"defaultEmailSub,omitempty"`
}

Config has all the configurations required for verifier package to function

type Request

type Request struct {
	ID           string            `json:"id,omitempty"`
	Type         CommType          `json:"type,omitempty"`
	Sender       string            `json:"sender,omitempty"`
	Recipient    string            `json:"recipient,omitempty"`
	Data         map[string]string `json:"data,omitempty"`
	Secret       string            `json:"secret,omitempty"`
	SecretExpiry *time.Time        `json:"secretExpiry,omitempty"`
	// Attempts has the number of times verification has been attempted
	Attempts int `json:"attempts,omitempty"`
	// CommStatus is the communication status, and is maintained as a list to later store
	// statuses of retries
	CommStatus []CommStatus       `json:"commStatus,omitempty"`
	Status     verificationStatus `json:"status,omitempty"`
	CreatedAt  *time.Time         `json:"createdAt,omitempty"`
	UpdatedAt  *time.Time         `json:"updatedAt,omitempty"`
}

Request struct holds all data related to a single verification request

type Verifier

type Verifier struct {
	// contains filtered or unexported fields
}

Verifier struct exposes all services provided by verify package

func New

func New(cfg *Config, verStore store, email emailService, mobile mobileService) (*Verifier, error)

New lets you customize various components

func (*Verifier) CustomEmailHandler

func (ver *Verifier) CustomEmailHandler(email emailService) error

CustomEmailHandler is used to set a custom email sending service

func (*Verifier) CustomMobileHandler

func (ver *Verifier) CustomMobileHandler(mobile mobileService) error

CustomMobileHandler is used to set a custom mobile message sending service

func (*Verifier) CustomStore

func (ver *Verifier) CustomStore(verStore store) error

CustomStore is used to set a custom persistent store

func (*Verifier) NewEmail

func (ver *Verifier) NewEmail(recipient, subject string) error

NewEmail creates a new request for email verification

func (*Verifier) NewEmailWithReq

func (ver *Verifier) NewEmailWithReq(verreq *Request, subject, body string) error

NewEmailWithReq is used to send a mail with a custom verification request

func (*Verifier) NewMobile

func (ver *Verifier) NewMobile(recipient string) error

NewMobile creates a new request for mobile number verification with default setting

func (*Verifier) NewMobileWithReq

func (ver *Verifier) NewMobileWithReq(verreq *Request, body string) error

NewMobileWithReq creates a new request for mobile number verification

func (*Verifier) NewRequest

func (ver *Verifier) NewRequest(ctype CommType, recipient string) (*Request, error)

NewRequest is used to create a new verification request

func (*Verifier) VerifyEmailSecret

func (ver *Verifier) VerifyEmailSecret(recipient, secret string) error

VerifyEmailSecret validates an email and its verification secret

func (*Verifier) VerifyMobileSecret

func (ver *Verifier) VerifyMobileSecret(recipient, secret string) error

VerifyMobileSecret validates a mobile number and its verification secret (OTP)