emailotp

type Config ¶

type Config struct {
	Provider  Provider      // Email sending provider (required for production)
	OTPExpiry time.Duration // OTP expiry duration (default: 10 minutes)
	OTPLength int           // OTP code length (default: 6)
}

Config holds Email OTP plugin configuration.

Example:

cfg := &emailotp.Config{
  Provider:  myEmailProvider,
  OTPExpiry: 15 * time.Minute,
  OTPLength: 8,
}

type DefaultEmailOTPStore ¶

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

DefaultEmailOTPStore implements EmailOTPStore using a SQL database.

This implementation uses sqlc-generated type-safe queries to manage users with email addresses in PostgreSQL, MySQL, or SQLite.

Database Schema: Extends the 'user' table with:

• email (VARCHAR, unique): User email address
• email_verified (BOOLEAN): Email verification status

Thread Safety: Safe for concurrent use through database transactions.

func NewDefaultEmailOTPStore(db *sql.DB) *DefaultEmailOTPStore

func (s *DefaultEmailOTPStore) CreateUser(ctx context.Context, user User) (*User, error)

func (s *DefaultEmailOTPStore) GetUserByEmail(ctx context.Context, email string) (*User, error)

func (s *DefaultEmailOTPStore) UpdateUserEmail(ctx context.Context, userID, email string, verified bool) error

type EncryptedOTPStorage ¶

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

EncryptedOTPStorage stores OTPs using AES-256-GCM encryption.

Security Characteristics:

• OTPs are encrypted with AES-256 (industry standard)
• GCM mode provides authenticated encryption
• Requires secure 32-byte encryption key

Use Cases:

• When OTPs need to be retrieved in plain text
• Audit logging requirements
• Multi-system verification

Security Warning: Key management is critical. Store encryption keys securely (environment variables, secrets management systems).

Example:

// From 32-byte key
key := []byte("12345678901234567890123456789012")  // Must be exactly 32 bytes
storage, _ := emailotp.NewEncryptedOTPStorage(key)

// From string (hashed to 32 bytes)
storage := emailotp.NewEncryptedOTPStorageFromString("my-secret-key")

func NewEncryptedOTPStorage(key []byte) (*EncryptedOTPStorage, error)

func NewEncryptedOTPStorageFromString(keyString string) *EncryptedOTPStorage

func (e *EncryptedOTPStorage) Compare(stored, input string) (bool, error)

func (e *EncryptedOTPStorage) Store(otp string) (string, error)

type Handlers ¶

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

Handlers encapsulates Email OTP plugin HTTP handlers.

func NewHandlers(plugin *Plugin) *Handlers

func (h *Handlers) LoginWithEmailHandler(w http.ResponseWriter, r *http.Request)

{
  "email": "user@example.com",
  "password": "SecurePassword123!"
}

{
  "success": true,
  "message": "Login successful",
  "data": {
    "user": {"id": "user_123", "email": "user@example.com", ...}
  }
}

func (h *Handlers) RegisterWithEmailHandler(w http.ResponseWriter, r *http.Request)

{
  "name": "John Doe",
  "email": "john@example.com",
  "password": "SecurePassword123!",
  "avatar": "https://example.com/avatar.jpg"  // Optional
}

{
  "success": true,
  "message": "Registration successful",
  "data": {
    "user": {"id": "user_123", "email": "john@example.com", "emailVerified": false}
  }
}

func (h *Handlers) SendOTPHandler(w http.ResponseWriter, r *http.Request)

{
  "email": "user@example.com",
  "userId": "user_123",
  "purpose": "email_verification"  // or "password_reset", "login_mfa"
}

{
  "success": true,
  "message": "OTP sent successfully"
}

func (h *Handlers) VerifyOTPHandler(w http.ResponseWriter, r *http.Request)

{
  "email": "user@example.com",
  "code": "123456",
  "purpose": "email_verification"
}

{
  "success": true,
  "message": "OTP verified successfully"
}

{
  "success": false,
  "error": "Invalid or expired OTP"
}

type HashedOTPStorage ¶

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

HashedOTPStorage stores OTPs using bcrypt hashing.

Security Benefits:

• OTPs cannot be reversed from database
• Resistant to rainbow table attacks
• Configurable work factor (cost)

Performance:

• Slower than plain text due to bcrypt cost
• Default cost: 10 (recommended balance)

Use Cases:

• Production environments
• High-security applications
• Compliance requirements (GDPR, PCI-DSS)

Example:

storage := emailotp.NewHashedOTPStorage(10)  // Cost factor 10
stored, _ := storage.Store("123456")        // Returns bcrypt hash
valid, _ := storage.Compare(stored, "123456") // true

func NewHashedOTPStorage(cost int) *HashedOTPStorage

func (h *HashedOTPStorage) Compare(stored, input string) (bool, error)

func (h *HashedOTPStorage) Store(otp string) (string, error)

type LoginWithEmailRequest ¶

type LoginWithEmailRequest struct {
	Email    string `json:"email"`    // User email address
	Password string `json:"password"` // User password
}

LoginWithEmailRequest represents email+password login request.

Example:

{
  "email": "user@example.com",
  "password": "SecurePassword123!"
}

type OTPStorageMethod ¶

type OTPStorageMethod interface {
	// Store encodes an OTP for database storage.
	//
	// Parameters:
	//   - otp: Plain text OTP code
	//
	// Returns:
	//   - string: Encoded OTP for storage
	//   - error: If encoding fails
	Store(otp string) (string, error)

	// Compare verifies an input OTP against the stored value.
	//
	// Parameters:
	//   - stored: Encoded OTP from database
	//   - input: Plain text OTP from user
	//
	// Returns:
	//   - bool: true if OTPs match
	//   - error: If comparison fails
	Compare(stored, input string) (bool, error)
}

OTPStorageMethod defines how OTPs are stored in the database.

This interface allows different storage strategies:

• PlainOTPStorage: Store OTPs in plain text (not recommended for production)
• HashedOTPStorage: Store bcrypt hashes (recommended, irreversible)
• EncryptedOTPStorage: Store AES-256-GCM encrypted OTPs (reversible)

Security Considerations:

• Plain text: Fast but insecure, suitable only for development
• Hashed: Secure but slower, best for production
• Encrypted: Reversible but requires secure key management

func NewOTPStorage(method string, encryptionKey string) (OTPStorageMethod, error)

type PlainOTPStorage ¶

type PlainOTPStorage struct{}

PlainOTPStorage stores OTPs in plain text.

Security Warning: This is NOT recommended for production. OTPs are stored without encryption, making them vulnerable to database breaches.

Use Cases:

• Development and testing
• Low-security environments

Example:

storage := emailotp.NewPlainOTPStorage()
stored, _ := storage.Store("123456")  // Returns "123456"

func NewPlainOTPStorage() *PlainOTPStorage

func (p *PlainOTPStorage) Compare(stored, input string) (bool, error)

func (p *PlainOTPStorage) Store(otp string) (string, error)

type Plugin ¶

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

Plugin provides email-based OTP verification and authentication.

This plugin integrates with email service providers to send OTP codes and supports email+password authentication as an alternative auth method.

Features:

• Configurable OTP length and expiry
• Pluggable email providers (SMTP, SendGrid, SES, etc.)
• Email address validation
• Password hashing with bcrypt
• Session management integration

func New(cfg *Config, store Store, dialect ...plugins.Dialect) *Plugin

plugin := emailotp.New(&emailotp.Config{
  Provider: mySMTPProvider,
  OTPExpiry: 15 * time.Minute,
  OTPLength: 8,
}, nil, plugins.DialectPostgres)

func (p *Plugin) CreateUserWithEmailAndPassword(ctx context.Context, name, email, password string) (*User, error)

user, err := plugin.CreateUserWithEmailAndPassword(ctx, "John Doe", "john@example.com", "SecurePass123!")

func (p *Plugin) Dependencies() []plugins.Dependency

func (p *Plugin) Description() string

func (p *Plugin) GetMigrations() []plugins.Migration

func (p *Plugin) GetSchemas() []plugins.Schema

func (p *Plugin) GetUserByEmail(ctx context.Context, email string) (*auth.User, error)

func (p *Plugin) Init(_ context.Context, a plugins.Aegis) error

func (p *Plugin) MountRoutes(router router.Router, prefix string)

func (p *Plugin) Name() string

func (p *Plugin) ProvidesAuthMethods() []string

func (p *Plugin) RequiresTables() []string

func (p *Plugin) SendOTP(ctx context.Context, emailAddress, purpose string) error

err := plugin.SendOTP(ctx, "user@example.com", "email_verification")

func (p *Plugin) VerifyOTP(ctx context.Context, emailAddress, code string) (bool, error)

valid, err := plugin.VerifyOTP(ctx, "user@example.com", "123456")
if valid {
  // Mark email as verified
}

func (p *Plugin) Version() string

type Provider ¶

type Provider interface {
	// SendOTP sends a one-time password to the specified email address.
	//
	// Parameters:
	//   - to: Recipient email address
	//   - code: OTP code to send (e.g., "123456")
	//
	// Returns:
	//   - error: If email sending fails
	SendOTP(to, code string) error

	// VerifyOTP verifies an OTP code for an email address.
	//
	// Note: Most implementations delegate verification to the plugin's OTP storage.
	// This method is available for provider-specific validation if needed.
	//
	// Parameters:
	//   - to: Email address to verify
	//   - code: OTP code to verify
	//
	// Returns:
	//   - bool: true if OTP is valid
	//   - error: If verification fails
	VerifyOTP(to, code string) (bool, error)
}

Provider is the interface that email service providers must implement.

Users should create their own implementation based on their email service (SMTP, SendGrid, Resend, AWS SES, Postmark, Mailgun, etc.).

Abstraction Benefits:

• Swap email providers without changing plugin code
• Test with mock providers
• Use different providers for different environments

Example Implementation (SMTP):

type SMTPProvider struct {
    host     string
    port     int
    username string
    password string
    from     string
}

func (p *SMTPProvider) SendOTP(to, code string) error {
    subject := "Your Verification Code"
    body := fmt.Sprintf("Your verification code is: %s\n\nThis code will expire in 10 minutes.", code)
    auth := smtp.PlainAuth("", p.username, p.password, p.host)
    msg := fmt.Sprintf("From: %s\r\nTo: %s\r\nSubject: %s\r\n\r\n%s", p.from, to, subject, body)
    return smtp.SendMail(p.host+":"+strconv.Itoa(p.port), auth, p.from, []string{to}, []byte(msg))
}

func (p *SMTPProvider) VerifyOTP(to, code string) (bool, error) {
    // Verification logic handled by plugin's OTP storage
    // This method can be used for provider-specific validation if needed
    return true, nil
}

Example Implementation (SendGrid):

type SendGridProvider struct {
    apiKey string
    from   string
}

func (p *SendGridProvider) SendOTP(to, code string) error {
    message := mail.NewV3Mail()
    message.SetFrom(mail.NewEmail("", p.from))
    message.AddContent(mail.NewContent("text/plain", fmt.Sprintf("Your OTP: %s", code)))
    personalization := mail.NewPersonalization()
    personalization.AddTos(mail.NewEmail("", to))
    message.AddPersonalizations(personalization)

    client := sendgrid.NewSendClient(p.apiKey)
    _, err := client.Send(message)
    return err
}

type RegisterWithEmailRequest ¶

type RegisterWithEmailRequest struct {
	Avatar   *string `json:"avatar"`   // Optional avatar URL
	Name     *string `json:"name"`     // User display name (required)
	Email    string  `json:"email"`    // User email address (required)
	Password string  `json:"password"` // User password (required)
}

RegisterWithEmailRequest represents email+password registration request.

Example:

{
  "name": "John Doe",
  "email": "john@example.com",
  "password": "SecurePassword123!",
  "avatar": "https://example.com/avatar.jpg"
}

type SendOTPRequest ¶

type SendOTPRequest struct {
	Email   string `json:"email"`   // Email address to send OTP to
	UserID  string `json:"userId"`  // User ID requesting OTP
	Purpose string `json:"purpose"` // OTP purpose ("email_verification", "password_reset", "login_mfa")
}

SendOTPRequest represents the request to send an OTP code.

Example:

{
  "email": "user@example.com",
  "userId": "user_123",
  "purpose": "email_verification"
}

type Store ¶

type Store interface {

	// CreateUser creates a new user with an email address.
	//
	// The email is initially unverified (emailVerified: false).
	//
	// Parameters:
	//   - ctx: Request context
	//   - user: User with email field populated
	//
	// Returns:
	//   - *User: Created user
	//   - error: If user creation fails (e.g., duplicate email)
	CreateUser(ctx context.Context, user User) (*User, error)

	// GetUserByEmail retrieves a user by email address.
	//
	// Used for:
	//   - Email+password login
	//   - Checking if email already exists during registration
	//   - Email verification lookup
	//
	// Parameters:
	//   - ctx: Request context
	//   - email: Email address to lookup
	//
	// Returns:
	//   - *User: User with matching email
	//   - error: If user not found or database error
	GetUserByEmail(ctx context.Context, email string) (*User, error)

	// UpdateUserEmail updates a user's email address and verification status.
	//
	// Used after successful OTP verification to mark email as verified.
	//
	// Parameters:
	//   - ctx: Request context
	//   - userID: User ID
	//   - email: New email address
	//   - verified: Email verification status
	//
	// Returns:
	//   - error: If update fails
	UpdateUserEmail(ctx context.Context, userID, email string, verified bool) error
}

Store defines the interface for Email OTP verification storage operations.

This interface provides email-specific user management operations:

• User creation with email addresses
• Email lookup for authentication
• Email verification status updates

Thread Safety: Implementations must be safe for concurrent use.

type User ¶

type User struct {
	auth.User
	Email         *string `json:"email,omitempty"` // User email address
	EmailVerified bool    `json:"emailVerified"`   // Email verification status
}

User extends the core User model with email-specific fields.

This model adds email verification status for display in API responses.

Use this when:

• Returning user data after email registration
• Displaying email verification status in user profiles
• Checking if user has verified their email

Example:

user := emailotp.User{
  User: auth.User{ID: "user_123", Name: "John Doe"},
  Email: ptr("john@example.com"),
  EmailVerified: true,
}

type VerifyOTPRequest ¶

type VerifyOTPRequest struct {
	Email   string `json:"email"`   // Email address to verify
	Code    string `json:"code"`    // OTP code to verify
	Purpose string `json:"purpose"` // OTP purpose
}

VerifyOTPRequest represents the request to verify an OTP code.

Example:

{
  "email": "user@example.com",
  "code": "123456",
  "purpose": "email_verification"
}