Documentation
¶
Overview ¶
Package emailotp provides email-based OTP (One-Time Password) verification and authentication.
This plugin enables:
- Email address verification via OTP codes
- Email+password registration and login
- Multi-factor authentication (MFA) via email
- Password reset via email verification
OTP Flow:
- User requests OTP via SendOTP endpoint (requires authentication)
- Plugin generates 6-digit code (configurable length)
- Code sent via configured email provider (SMTP, SendGrid, etc.)
- Code stored in database with expiry (default: 10 minutes)
- User submits code via VerifyOTP endpoint
- Plugin validates code and marks email as verified
Email+Password Flow:
- User registers with email+password via /register endpoint
- Password hashed with bcrypt and stored
- User can login with email+password via /login endpoint
- Session created on successful authentication
Route Structure:
- POST /email-otp/send - Send OTP code (protected)
- POST /email-otp/verify - Verify OTP code (public)
- POST /email-otp/login - Login with email+password (public)
- POST /email-otp/register - Register with email+password (public)
Provider Integration: Implement the Provider interface to use your email service:
type MySMTPProvider struct { host, user, pass string }
func (p *MySMTPProvider) SendOTP(to, code string) error {
// Send email with OTP code
}
Index ¶
- Constants
- func GetMigrations(dialect plugins.Dialect) ([]plugins.Migration, error)
- func ValidateEmail(email string) error
- type Config
- type Handlers
- type Plugin
- func (p *Plugin) CreateUserWithEmailAndPassword(ctx context.Context, name, email, password string) (*emailotptypes.User, error)
- func (p *Plugin) Dependencies() []plugins.Dependency
- func (p *Plugin) Description() string
- func (p *Plugin) EnrichUser(ctx context.Context, user *core.EnrichedUser) error
- func (p *Plugin) GetMigrations() []plugins.Migration
- 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) MarkEmailVerified(ctx context.Context, email string) error
- func (p *Plugin) MountRoutes(r 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
- func (p *Plugin) UpdateUserEmail(ctx context.Context, userID, email string, verified bool) error
- func (p *Plugin) VerifyOTP(ctx context.Context, emailAddress, code string) (bool, error)
- func (p *Plugin) Version() string
- type Provider
Constants ¶
const ( // Request schemas SchemaLoginWithEmailRequest = "LoginWithEmailRequest" SchemaRegisterWithEmailRequest = "RegisterWithEmailRequest" SchemaSendOTPRequest = "SendOTPRequest" SchemaVerifyOTPRequest = "VerifyOTPRequest" )
Schema names for OpenAPI specification generation.
These constants define the OpenAPI schema names for emailotp request/response types. They are used in route metadata to generate accurate API documentation with typed request/response examples.
Variables ¶
This section is empty.
Functions ¶
func GetMigrations ¶
GetMigrations returns all database migrations for the emailotp plugin.
This function loads migrations from embedded SQL files and returns them in version order.
Version Numbering:
- Version 001+: Migrations from migrations/<dialect>/<version>_<description>.<up|down>.sql
Migration File Format:
- Up migration: 001_initial.up.sql
- Down migration: 001_initial.down.sql
Parameters:
- dialect: Database dialect (postgres, mysql, sqlite)
Returns:
- []plugins.Migration: Sorted list of migrations (oldest first)
- error: If migration files cannot be read or parsed
func ValidateEmail ¶
ValidateEmail validates an email address format using RFC 5322 regex.
Parameters:
- email: Email address to validate
Returns:
- error: If email is empty or has invalid format
Types ¶
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 Handlers ¶
type Handlers struct {
// contains filtered or unexported fields
}
Handlers encapsulates Email OTP plugin HTTP handlers.
func NewHandlers ¶
NewHandlers creates Email OTP plugin handlers.
Parameters:
- plugin: Initialized Email OTP plugin
Returns:
- *Handlers: Handler instance ready for route registration
func (*Handlers) SendOTPHandler ¶
func (h *Handlers) SendOTPHandler(w http.ResponseWriter, r *http.Request)
SendOTPHandler handles sending OTP via email.
This endpoint is protected to prevent spam/abuse. Only authenticated users can request OTP codes.
Endpoint:
- Method: POST
- Path: /email-otp/send
- Auth: Required (session)
Request Body:
{
"email": "user@example.com",
"userId": "user_123",
"purpose": "email_verification" // or "password_reset", "login_mfa"
}
Response (200 OK):
{
"success": true,
"message": "OTP sent successfully"
}
func (*Handlers) VerifyOTPHandler ¶
func (h *Handlers) VerifyOTPHandler(w http.ResponseWriter, r *http.Request)
VerifyOTPHandler handles verifying OTP codes.
This endpoint is public to allow users to verify their email addresses without requiring prior authentication.
Endpoint:
- Method: POST
- Path: /email-otp/verify
- Auth: Public
Request Body:
{
"email": "user@example.com",
"code": "123456",
"purpose": "email_verification"
}
Response (200 OK):
{
"success": true,
"message": "OTP verified successfully"
}
Response (400 Bad Request):
{
"success": false,
"error": "Invalid or expired OTP"
}
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 ¶
New creates a new Email OTP plugin instance.
Parameters:
- cfg: Plugin configuration (can be nil for defaults)
- store: Custom Store implementation (can be nil, will use DefaultEmailOTPStore)
- dialect: Database dialect (optional, defaults to PostgreSQL)
Returns:
- *Plugin: Configured plugin ready for initialization
Example:
plugin := emailotp.New(&emailotp.Config{
Provider: mySMTPProvider,
OTPExpiry: 15 * time.Minute,
OTPLength: 8,
}, nil, plugins.DialectPostgres)
func (*Plugin) CreateUserWithEmailAndPassword ¶
func (p *Plugin) CreateUserWithEmailAndPassword(ctx context.Context, name, email, password string) (*emailotptypes.User, error)
CreateUserWithEmailAndPassword creates a new user with email+password authentication.
Registration Process:
- Create user record with email (unverified)
- Hash password with bcrypt
- Create password account in auth.accounts table
- Return user for session creation
Parameters:
- ctx: Request context
- name: User display name
- email: User email address (becomes primary identifier)
- password: Plain text password (will be hashed)
Returns:
- *User: Created user with email field
- error: If user creation or password hashing fails
Example:
user, err := plugin.CreateUserWithEmailAndPassword(ctx, "John Doe", "john@example.com", "SecurePass123!")
func (*Plugin) Dependencies ¶
func (p *Plugin) Dependencies() []plugins.Dependency
Dependencies returns external package dependencies
func (*Plugin) Description ¶
Description returns a human-readable description for logging.
func (*Plugin) EnrichUser ¶ added in v1.2.1
EnrichUser implements plugins.UserEnricher to add email verification status.
This method is called automatically by the authentication system after user lookup. It adds the user's email verification status to the EnrichedUser, making it available in API responses without requiring separate queries.
Fields Added:
- "emailVerified" (bool): Whether the user's email has been verified
Parameters:
- ctx: Request context
- user: EnrichedUser to populate with email verification data
Returns:
- error: Always nil (lookup failure is not an error)
func (*Plugin) GetMigrations ¶
GetMigrations returns the plugin migrations
func (*Plugin) GetUserByEmail ¶
GetUserByEmail retrieves a user by email address
func (*Plugin) MarkEmailVerified ¶ added in v1.2.2
MarkEmailVerified marks a user's email as verified in the database.
This is called automatically by VerifyOTPHandler after successful OTP verification. It can also be called programmatically to mark an email as verified.
Parameters:
- ctx: Request context
- email: Email address to mark as verified
Returns:
- error: If user lookup or update fails
Example:
err := plugin.MarkEmailVerified(ctx, "user@example.com")
func (*Plugin) MountRoutes ¶
MountRoutes registers HTTP routes for the Email OTP plugin
func (*Plugin) ProvidesAuthMethods ¶
ProvidesAuthMethods returns authentication methods provided
func (*Plugin) RequiresTables ¶
RequiresTables returns the core tables this plugin reads from.
func (*Plugin) SendOTP ¶
SendOTP generates and sends an OTP code via email.
OTP Generation and Delivery:
- Generate random N-digit code (configurable length)
- Send code via email provider
- Store code in verification service with expiry
- Invalidate any previous OTPs for same email+purpose
Parameters:
- ctx: Request context
- emailAddress: Recipient email address
- purpose: OTP purpose ("email_verification", "password_reset", "login_mfa")
Returns:
- error: If OTP generation or sending fails
Example:
err := plugin.SendOTP(ctx, "user@example.com", "email_verification")
func (*Plugin) UpdateUserEmail ¶ added in v1.2.2
UpdateUserEmail updates a user's email address and verification status programmatically.
Parameters:
- ctx: Request context
- userID: User ID to update
- email: New email address
- verified: Whether the email is verified
Returns:
- error: If update fails
Example:
err := plugin.UpdateUserEmail(ctx, "user_123", "new@example.com", false)
func (*Plugin) VerifyOTP ¶
VerifyOTP verifies an OTP code for an email address.
Verification Process:
- Check if provider supports OTP verification (rare)
- Fall back to core verification service (standard)
- Validate code and check expiry
- Return success/failure
Parameters:
- ctx: Request context
- emailAddress: Email address to verify
- code: OTP code to verify (e.g., "123456")
Returns:
- bool: true if OTP is valid and not expired
- error: If verification fails
VerifyOTP verifies an OTP code for the given email address.
Example:
valid, err := plugin.VerifyOTP(ctx, "user@example.com", "123456")
if valid {
// Mark email as verified
}
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
}
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package defaultstore implements the SQL-backed default store for the emailotp plugin.
|
Package defaultstore implements the SQL-backed default store for the emailotp plugin. |
|
internal
|
|
|
Package types defines the domain models and request/response types used by the emailotp plugin.
|
Package types defines the domain models and request/response types used by the emailotp plugin. |