magiclink

Documentation

Overview

Package magiclink provides passwordless magic-link authentication for Limen.

Index

• Constants
• Variables
• func New(opts ...ConfigOption) *magicLinkPlugin
• type API
  • func Use(a *limen.Limen) API
• type ConfigOption
  • func WithAutoCreateUser(autoCreateUser bool) ConfigOption
  • func WithGenerateToken(generateToken func(email string) (string, error)) ConfigOption
  • func WithMapMetaToUser(mapper func(map[string]any) map[string]any) ConfigOption
  • func WithMarkEmailVerified(markEmailVerified bool) ConfigOption
  • func WithMaxUses(maxUses int) ConfigOption
  • func WithSendMagicLink(sendMagicLink func(MagicLinkMessage)) ConfigOption
  • func WithTokenExpiration(expiration time.Duration) ConfigOption
• type MagicLinkMessage
• type MagicLinkState
• type RequestMagicLinkOptions

Constants

const (
	MagicLinkAction = "magic_link"
)

Variables

var (
	ErrEmailRequired                 = limen.NewLimenError("email is required", http.StatusUnprocessableEntity, nil)
	ErrEmailNotFound                 = limen.NewLimenError("email not found", http.StatusNotFound, nil)
	ErrMagicLinkTokenInvalid         = limen.NewLimenError("invalid or expired magic link token", http.StatusBadRequest, nil)
	ErrMagicLinkTokenMaxUsesExceeded = limen.NewLimenError("magic link token has reached the maximum number of uses", http.StatusBadRequest, nil)
	ErrMaxUsesInvalid                = limen.NewLimenError("max uses must be greater than zero", http.StatusUnprocessableEntity, nil)
)

Functions

func New

func New(opts ...ConfigOption) *magicLinkPlugin

New creates a magic-link plugin with sensible passwordless-auth defaults.

Types

type API

type API interface {
	RequestMagicLink(ctx context.Context, email string, opts ...*RequestMagicLinkOptions) (*MagicLinkMessage, error)
	VerifyMagicLink(ctx context.Context, token string) (*limen.AuthenticationResult, *MagicLinkState, error)
}

API is the public interface for the magic-link plugin. Call Use to obtain a type-safe reference from a Limen instance.

func Use

func Use(a *limen.Limen) API

Use returns a type-safe API for the magic-link plugin. Panics if the plugin was not registered in Config.Plugins.

type ConfigOption

type ConfigOption func(*config)

ConfigOption configures the magic-link plugin.

func WithAutoCreateUser

func WithAutoCreateUser(autoCreateUser bool) ConfigOption

WithAutoCreateUser controls whether unknown emails create a user by default.

func WithGenerateToken

func WithGenerateToken(generateToken func(email string) (string, error)) ConfigOption

WithGenerateToken sets the token generator used for new magic links.

func WithMapMetaToUser

func WithMapMetaToUser(mapper func(map[string]any) map[string]any) ConfigOption

WithMapMetaToUser maps magic-link metadata into fields used when auto-creating a new user. By default, request metadata is kept in magic-link state only and is not persisted to the user record.

func WithMarkEmailVerified

func WithMarkEmailVerified(markEmailVerified bool) ConfigOption

WithMarkEmailVerified controls whether successful magic-link login verifies the email.

func WithMaxUses

func WithMaxUses(maxUses int) ConfigOption

WithMaxUses sets the default number of times a generated magic link can be used.

func WithSendMagicLink

func WithSendMagicLink(sendMagicLink func(MagicLinkMessage)) ConfigOption

WithSendMagicLink sets the callback used to deliver a magic link.

func WithTokenExpiration

func WithTokenExpiration(expiration time.Duration) ConfigOption

WithTokenExpiration sets how long generated magic links remain valid.

type MagicLinkMessage

type MagicLinkMessage struct {
	Email          string
	Token          string
	URL            string
	AdditionalData map[string]any
}

type MagicLinkState

type MagicLinkState struct {
	Email              string         `json:"e"`
	UsedCount          int            `json:"c"`
	RedirectURI        string         `json:"r,omitempty"`
	NewUserRedirectURI string         `json:"nr,omitempty"`
	ErrorRedirectURI   string         `json:"er,omitempty"`
	AdditionalData     map[string]any `json:"a,omitempty"`
	Nonce              string         `json:"n,omitempty"`
	IsNewUser          bool           `json:"-"`
}

MagicLinkState is the per-request state persisted alongside a magic-link verification token. It captures the redirect targets supplied at request time and information resolved during verification (such as whether the sign-in was for a newly created user).

type RequestMagicLinkOptions

type RequestMagicLinkOptions struct {
	RedirectURI        string
	NewUserRedirectURI string
	ErrorRedirectURI   string
	AdditionalData     map[string]any
}