verifier

README

Verifier v0.1.0

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

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)