twofa

package
v0.0.11 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 3, 2026 License: Apache-2.0 Imports: 20 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Register 

func Register(router forge.Router, basePath string, h *Handler)

Register registers 2FA routes under basePath

Types

type CodesResponse 

type CodesResponse struct {
	Codes []string `json:"codes"`
}

Plugin-specific responses

type Config 

type Config struct {
	// TOTPIssuer is the issuer name shown in authenticator apps
	TOTPIssuer string `json:"totpIssuer"`
	// TOTPPeriod is the TOTP time period in seconds
	TOTPPeriod int `json:"totpPeriod"`
	// TOTPDigits is the number of digits in TOTP code
	TOTPDigits int `json:"totpDigits"`
	// BackupCodeCount is the number of backup codes to generate
	BackupCodeCount int `json:"backupCodeCount"`
	// BackupCodeLength is the length of each backup code
	BackupCodeLength int `json:"backupCodeLength"`
	// OTPExpiryMinutes is the OTP expiry time in minutes
	OTPExpiryMinutes int `json:"otpExpiryMinutes"`
	// MaxOTPAttempts is the maximum failed OTP attempts before lockout
	MaxOTPAttempts int `json:"maxOtpAttempts"`
	// TrustedDeviceDays is the number of days a device remains trusted
	TrustedDeviceDays int `json:"trustedDeviceDays"`
	// RequireFor2FA forces 2FA for all users
	RequireFor2FA bool `json:"requireFor2FA"`
}

Config holds the 2FA plugin configuration

func DefaultConfig 

func DefaultConfig() Config

DefaultConfig returns the default 2FA plugin configuration

type DisableRequest added in v0.0.7 

type DisableRequest struct {
	UserID string `json:"user_id" validate:"required"`
}

type EnableRequest 

type EnableRequest struct {
	Method string // "totp" or "otp"
}

type EnableRequest2FA added in v0.0.7 

type EnableRequest2FA struct {
	UserID string `json:"user_id" validate:"required"`
	Method string `json:"method"`
}

Request types

type EnableResponse added in v0.0.7 

type EnableResponse struct {
	Status  string `json:"status"`
	TOTPURI string `json:"totp_uri,omitempty"`
}

type GetStatusRequest added in v0.0.7 

type GetStatusRequest struct {
	UserID   string `json:"user_id" validate:"required"`
	DeviceID string `json:"device_id"`
}

type Handler 

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

Handler exposes HTTP endpoints for 2FA operations

func NewHandler 

func NewHandler(s *Service) *Handler

func (*Handler) Disable 

func (h *Handler) Disable(c forge.Context) error

func (*Handler) Enable 

func (h *Handler) Enable(c forge.Context) error

func (*Handler) GenerateBackupCodes 

func (h *Handler) GenerateBackupCodes(c forge.Context) error

func (*Handler) SendOTP 

func (h *Handler) SendOTP(c forge.Context) error

SendOTP triggers generation of an OTP code for a user (returns code in response for dev/testing)

func (*Handler) Status 

func (h *Handler) Status(c forge.Context) error

Status returns whether 2FA is enabled and whether the device is trusted

func (*Handler) Verify 

func (h *Handler) Verify(c forge.Context) error

type OTPSentResponse 

type OTPSentResponse struct {
	Status string `json:"status"`
	Code   string `json:"code"`
}

type Plugin 

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

Plugin implements the plugins.Plugin interface for Two-Factor Authentication

func NewPlugin 

func NewPlugin(opts ...PluginOption) *Plugin

NewPlugin creates a new 2FA plugin instance with optional configuration

func (*Plugin) ID 

func (p *Plugin) ID() string

func (*Plugin) Init 

func (p *Plugin) Init(authInst core.Authsome) error

func (*Plugin) Migrate 

func (p *Plugin) Migrate() error

func (*Plugin) RegisterHooks 

func (p *Plugin) RegisterHooks(_ *hooks.HookRegistry) error

func (*Plugin) RegisterRoutes 

func (p *Plugin) RegisterRoutes(router forge.Router) error

RegisterRoutes registers 2FA endpoints under the auth base

func (*Plugin) RegisterServiceDecorators 

func (p *Plugin) RegisterServiceDecorators(_ *registry.ServiceRegistry) error

type PluginOption 

type PluginOption func(*Plugin)

PluginOption is a functional option for configuring the 2FA plugin

func WithBackupCodeCount 

func WithBackupCodeCount(count int) PluginOption

WithBackupCodeCount sets the number of backup codes

func WithBackupCodeLength 

func WithBackupCodeLength(length int) PluginOption

WithBackupCodeLength sets the backup code length

func WithDefaultConfig 

func WithDefaultConfig(cfg Config) PluginOption

WithDefaultConfig sets the default configuration for the plugin

func WithMaxOTPAttempts 

func WithMaxOTPAttempts(max int) PluginOption

WithMaxOTPAttempts sets the max OTP attempts

func WithOTPExpiryMinutes 

func WithOTPExpiryMinutes(minutes int) PluginOption

WithOTPExpiryMinutes sets the OTP expiry time

func WithRequireFor2FA 

func WithRequireFor2FA(required bool) PluginOption

WithRequireFor2FA sets whether 2FA is required for all users

func WithTOTPIssuer 

func WithTOTPIssuer(issuer string) PluginOption

WithTOTPIssuer sets the TOTP issuer name

func WithTOTPPeriod 

func WithTOTPPeriod(period int) PluginOption

WithTOTPPeriod sets the TOTP time period

func WithTrustedDeviceDays 

func WithTrustedDeviceDays(days int) PluginOption

WithTrustedDeviceDays sets the trusted device duration

type RegenerateCodesRequest added in v0.0.7 

type RegenerateCodesRequest struct {
	UserID string `json:"user_id" validate:"required"`
	Count  int    `json:"count"`
}

type SendOTPRequest added in v0.0.7 

type SendOTPRequest struct {
	UserID string `json:"user_id" validate:"required"`
}

type Service 

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

Service provides Two-Factor Authentication operations

func NewService 

func NewService(r *repo.TwoFARepository, config Config) *Service

func (*Service) BackupCodes 

func (s *Service) BackupCodes(ctx context.Context, userID string, count int) ([]string, error)

BackupCodes generates cryptographically secure recovery codes for 2FA

func (*Service) CleanupExpiredDevices 

func (s *Service) CleanupExpiredDevices(ctx context.Context) error

CleanupExpiredDevices removes expired trusted device records

func (*Service) Disable 

func (s *Service) Disable(ctx context.Context, userID string) error

Disable removes 2FA for a user

func (*Service) Enable 

func (s *Service) Enable(ctx context.Context, userID string, req *EnableRequest) (*TOTPSecret, error)

Enable sets up 2FA for a user using the specified method

func (*Service) GenerateBackupCodes 

func (s *Service) GenerateBackupCodes(ctx context.Context, userID string, count int) ([]string, error)

GenerateBackupCodes returns a set of backup recovery codes

func (*Service) GenerateTOTPSecret 

func (s *Service) GenerateTOTPSecret(ctx context.Context, userID string) (*TOTPSecret, error)

GenerateTOTPSecret creates a new TOTP secret and provisioning URI

func (*Service) GetStatus 

func (s *Service) GetStatus(ctx context.Context, userID, deviceID string) (*Status, error)

GetStatus returns 2FA enabled/method and whether device is trusted

func (*Service) IsTrusted 

func (s *Service) IsTrusted(ctx context.Context, userID, deviceID string) (bool, error)

func (*Service) IsTrustedDevice 

func (s *Service) IsTrustedDevice(ctx context.Context, userID, deviceID string) bool

IsTrustedDevice checks if a device is currently trusted (not expired)

func (*Service) ListTrustedDevices 

func (s *Service) ListTrustedDevices(ctx context.Context, userID string) ([]schema.TrustedDevice, error)

ListTrustedDevices returns all trusted devices for a user

func (*Service) MarkTrusted 

func (s *Service) MarkTrusted(ctx context.Context, userID, deviceID string, days int) error

Trusted devices helpers (stubs)

func (*Service) MarkTrustedDevice 

func (s *Service) MarkTrustedDevice(ctx context.Context, userID, deviceID string, days int) error

MarkTrustedDevice marks a device as trusted for a specified number of days

func (*Service) RemoveTrustedDevice 

func (s *Service) RemoveTrustedDevice(ctx context.Context, userID, deviceID string) error

RemoveTrustedDevice removes trust for a specific device

func (*Service) SendOTP 

func (s *Service) SendOTP(ctx context.Context, userID string) (string, error)

SendOTP generates and stores a one-time password; returns the code for delivery

func (*Service) Verify 

func (s *Service) Verify(ctx context.Context, userID string, req *VerifyRequest) (bool, error)

Verify validates a provided 2FA code

func (*Service) VerifyBackupCode 

func (s *Service) VerifyBackupCode(ctx context.Context, userID, code string) (bool, error)

VerifyBackupCode validates a backup code and marks it as used

func (*Service) VerifyOTP 

func (s *Service) VerifyOTP(ctx context.Context, userID, code string) (bool, error)

VerifyOTP verifies a one-time password against stored hash

func (*Service) VerifyTOTP 

func (s *Service) VerifyTOTP(userID, code string) (bool, error)

VerifyTOTP checks a TOTP code against stored secret

type Status 

type Status struct {
	Enabled bool
	Method  string
	Trusted bool
}

Status provides the current 2FA status and device trust state

type StatusResponse 

type StatusResponse = responses.StatusResponse

Response types - use shared responses from core

type TOTPSecret 

type TOTPSecret struct {
	Secret string
	URI    string
}

TOTPSecret represents a generated TOTP secret bundle

type TwoFABackupCodesResponse 

type TwoFABackupCodesResponse struct {
	Codes []string `json:"codes" example:"12345678,87654321"`
}

type TwoFAEnableResponse 

type TwoFAEnableResponse struct {
	Status  string `json:"status" example:"2fa_enabled"`
	TOTPURI string `json:"totp_uri,omitempty" example:"otpauth://totp/AuthSome:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=AuthSome"`
}

type TwoFAErrorResponse 

type TwoFAErrorResponse struct {
	Error string `json:"error" example:"Error message"`
}

Response types for 2FA routes

type TwoFASendOTPResponse 

type TwoFASendOTPResponse struct {
	Status string `json:"status" example:"otp_sent"`
	Code   string `json:"code,omitempty" example:"123456"`
}

type TwoFAStatusDetailResponse 

type TwoFAStatusDetailResponse struct {
	Enabled bool   `json:"enabled" example:"true"`
	Method  string `json:"method,omitempty" example:"totp"`
	Trusted bool   `json:"trusted,omitempty" example:"false"`
}

type TwoFAStatusResponse 

type TwoFAStatusResponse struct {
	Enabled bool   `json:"enabled"`
	Method  string `json:"method"`
	Trusted bool   `json:"trusted"`
}

type VerifyRequest 

type VerifyRequest struct {
	Code string
}

type VerifyRequest2FA added in v0.0.7 

type VerifyRequest2FA struct {
	UserID         string `json:"user_id" validate:"required"`
	Code           string `json:"code" validate:"required"`
	RememberDevice bool   `json:"remember_device"`
	DeviceID       string `json:"device_id"`
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.