magiclink

type AuthenticateInput struct {
	// Token is the plaintext single-use token received by the user. Required.
	Token string

	// Session holds optional metadata (IP address, User Agent) recorded with the session.
	Session auth.SessionOptions
}

type BeforeConsumeHook func(ctx context.Context, in *AuthenticateInput) error

type BeforeRequestHook func(ctx context.Context, in *RequestInput) error

type Capability = MagicLink

type Config struct {
	// TTL is the lifetime of an issued magic link token.
	// Default: 15 minutes.
	TTL time.Duration

	// AllowSignUp allows automatically creating a new user and account
	// if the requested email is not already registered.
	// Default: false (only existing users can authenticate).
	AllowSignUp bool

	// RevokePreviousOnRequest deletes any active magic link tokens for the subject
	// when a new magic link is requested.
	// Default: true.
	RevokePreviousOnRequest bool

	// BaseURL is an optional base URL used to construct the full magic link URL.
	// e.g. "https://myapp.com/auth/magiclink/verify".
	// The token is appended as a query parameter ("?token=").
	BaseURL string

	// RateLimit configures optional request throttling and cooldowns.
	RateLimit RateLimitConfig

	// MessageBuilder formats the transactional email.
	MessageBuilder MessageBuilder

	// EmailSender overrides the email sender configured on the host.
	EmailSender email.Sender

	// Hooks provides access to pre-request and pre-consume security hooks.
	Hooks *Hooks
}

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

type MagicLink interface {
	// Request initiates the passwordless authentication flow for the given email address.
	// If the user does not exist and AllowSignUp is false, it returns nil to prevent user enumeration.
	Request(ctx context.Context, in RequestInput) error

	// Authenticate validates and atomically consumes the single-use magic link token,
	// establishes a server-side session, and returns the authentication result.
	Authenticate(ctx context.Context, in AuthenticateInput) (*auth.AuthResult, error)

	// Revoke deletes all active magic link tokens issued for the given email address.
	Revoke(ctx context.Context, email string) error
}

type MagicLinkConsumedPayload struct {
	UserID     string    `json:"user_id"`
	Email      string    `json:"email"`
	SessionID  string    `json:"session_id"`
	ConsumedAt time.Time `json:"consumed_at"`
}

type MagicLinkRequestedPayload struct {
	Email     string    `json:"email"`
	Subject   string    `json:"subject"`
	ExpiresAt time.Time `json:"expires_at"`
}

type MessageBuilder func(to string, token string, verificationURL string) email.Message

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

type Option func(*Config)

type RateLimitConfig struct {
	// Enabled determines whether rate limiting is active.
	Enabled bool

	// Max is the maximum number of requests allowed in Window.
	// Default: 5 requests.
	Max int

	// Window is the time window for rate limiting.
	// Default: 15 minutes.
	Window time.Duration

	// Cooldown is the minimum duration required between consecutive requests for the same email.
	// Default: 60 seconds.
	Cooldown time.Duration
}

type RequestInput struct {
	// Email is the destination email address. Required.
	Email string

	// Metadata carries optional application context.
	Metadata map[string]string
}