magiclink

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

type Cipher interface {
	// Encrypt encrypts a plain text token into a secure string representation.
	Encrypt(token string) (string, error)

	// Decrypt decrypts an encrypted string back into the original plain text token.
	Decrypt(encrypted string) (string, error)
}

type Config struct {
	// SendMagicLink is the required callback function for dispatching email links.
	SendMagicLink SendMagicLinkFunc

	// ExpiresIn specifies the lifetime of generated magic link tokens (default: 5 minutes).
	ExpiresIn time.Duration

	// DisableSignUp prevents creation of new accounts when an email is not yet registered (default: false).
	DisableSignUp bool

	// DefaultCallbackURL specifies the fallback redirect URL after successful verification.
	DefaultCallbackURL string

	// GenerateToken allows overriding the default random token generator.
	GenerateToken TokenGeneratorFunc

	// StoreTokenMode defines token persistence security ("plain", "hashed", "encrypted", default: "plain").
	StoreTokenMode StoreTokenMode

	// SecretKey is the symmetric key used when StoreTokenMode is "encrypted".
	SecretKey string

	// CustomHasher allows overriding the default SHA-256 token hasher.
	CustomHasher Hasher

	// CustomCipher allows overriding the default AES-256-GCM cipher.
	CustomCipher Cipher

	// RateLimit holds rate limiting rules for magic link requests.
	RateLimit RateLimitConfig
}

type DefaultSHA256Hasher struct{}

type Hasher interface {
	// Hash computes the one-way cryptographic hash of a token.
	Hash(token string) (string, error)

	// Verify compares a plain text token against the stored hash in constant time.
	Verify(token, hashed string) bool
}

type MagicLinkFailedPayload struct {
	Email  string         `json:"email,omitempty"`
	Token  string         `json:"token,omitempty"`
	Reason string         `json:"reason"`
	Extra  map[string]any `json:"extra,omitempty"`
}

type MagicLinkSentPayload struct {
	Email     string         `json:"email"`
	URL       string         `json:"url"`
	ExpiresAt time.Time      `json:"expires_at"`
	Extra     map[string]any `json:"extra,omitempty"`
}

type MagicLinkVerifiedPayload struct {
	Email     string       `json:"email"`
	User      *entity.User `json:"user"`
	IsNewUser bool         `json:"is_new_user"`
}

type Option func(*Config)

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

type RateLimitConfig struct {
	// Window specifies the sliding rate limit time window.
	Window time.Duration `json:"window"`

	// Max specifies the maximum allowed requests within the configured window.
	Max int `json:"max"`
}

type Repository interface {
	// CreateVerificationValue creates a new verification record in persistent storage.
	CreateVerificationValue(ctx context.Context, record *VerificationRecord) error

	// FindVerificationValue retrieves an active verification record matching the given identifier.
	FindVerificationValue(ctx context.Context, identifier string) (*VerificationRecord, error)

	// ConsumeVerificationValue atomically retrieves and removes/invalidates a verification record by identifier.
	// This operation MUST be single-use to protect against race conditions and token replay attacks.
	ConsumeVerificationValue(ctx context.Context, identifier string) (*VerificationRecord, error)

	// DeleteVerificationValue removes a verification record from persistent storage.
	DeleteVerificationValue(ctx context.Context, identifier string) error

	// FindUserByEmail retrieves a user by their email address.
	FindUserByEmail(ctx context.Context, email string) (*entity.User, error)

	// CreateUser persists a new user entity in storage.
	CreateUser(ctx context.Context, user *entity.User) (*entity.User, error)

	// UpdateEmailVerified updates the email verification status for a specific user.
	UpdateEmailVerified(ctx context.Context, userID string, verified bool) error

	// CreateSession initializes and persists an active user session.
	CreateSession(ctx context.Context, session *entity.Session) (*entity.Session, error)
}

type SendMagicLinkData struct {
	// Email is the target recipient email address.
	Email string `json:"email"`

	// Name is an optional recipient display name.
	Name string `json:"name,omitempty"`

	// URL is the generated full verification URL including token and query parameters.
	URL string `json:"url"`

	// Token is the raw verification token string.
	Token string `json:"token"`

	// CallbackURL is the destination URL to redirect upon successful verification.
	CallbackURL string `json:"callback_url,omitempty"`

	// NewUserCallbackURL is an optional destination URL for newly registered users.
	NewUserCallbackURL string `json:"new_user_callback_url,omitempty"`

	// ErrorCallbackURL is an optional destination URL on verification failures.
	ErrorCallbackURL string `json:"error_callback_url,omitempty"`

	// Extra holds dynamic metadata passed through request parameters or hooks.
	Extra map[string]any `json:"extra,omitempty"`
}

type SendMagicLinkFunc func(ctx context.Context, data SendMagicLinkData) error

type SendMagicLinkPendingPayload struct {
	Email     string         `json:"email"`
	URL       string         `json:"url"`
	ExpiresAt time.Time      `json:"expires_at"`
	Extra     map[string]any `json:"extra,omitempty"`
}

type SignInMagicLinkParams struct {
	// Email is the target recipient email address (required).
	Email string `json:"email"`

	// Name is an optional recipient display name.
	Name string `json:"name,omitempty"`

	// CallbackURL is the target redirect URL after successful verification.
	CallbackURL string `json:"callback_url,omitempty"`

	// NewUserCallbackURL is an optional target redirect URL for newly created users.
	NewUserCallbackURL string `json:"new_user_callback_url,omitempty"`

	// ErrorCallbackURL is an optional target redirect URL on verification error.
	ErrorCallbackURL string `json:"error_callback_url,omitempty"`

	plugin.ExtraContainer
}

type SignInMagicLinkResult struct {
	// Success indicates if the magic link was generated and dispatched.
	Success bool `json:"success"`

	// ExpiresAt indicates when the dispatched magic link token will expire.
	ExpiresAt time.Time `json:"expires_at"`
}

type SignInSuccessPayload struct {
	User      *entity.User    `json:"user"`
	Session   *entity.Session `json:"session"`
	IsNewUser bool            `json:"is_new_user"`
}

type StoreTokenMode string

type TokenGeneratorFunc func(ctx context.Context, email string) (string, error)

type TokenPayload struct {
	Token              string         `json:"token"`
	Email              string         `json:"email"`
	Name               string         `json:"name,omitempty"`
	CallbackURL        string         `json:"callback_url,omitempty"`
	NewUserCallbackURL string         `json:"new_user_callback_url,omitempty"`
	ErrorCallbackURL   string         `json:"error_callback_url,omitempty"`
	Extra              map[string]any `json:"extra,omitempty"`
}

type VerificationRecord struct {
	// ID is the unique database record identifier.
	ID string `json:"id"`

	// Identifier is the composite lookup key (e.g. "magic-link-token-user@example.com").
	Identifier string `json:"identifier"`

	// Value stores the token value (or hashed/encrypted token) along with metadata payload.
	Value string `json:"value"`

	// ExpiresAt specifies the exact timestamp after which this token is invalid.
	ExpiresAt time.Time `json:"expires_at"`

	// CreatedAt records when the token record was initialized.
	CreatedAt time.Time `json:"created_at"`

	// UpdatedAt records when the token record was last modified.
	UpdatedAt time.Time `json:"updated_at"`
}

type VerifyBeforePayload struct {
	Token string         `json:"token"`
	Extra map[string]any `json:"extra,omitempty"`
}

type VerifyMagicLinkParams struct {
	// Token is the magic link verification token string (required).
	Token string `json:"token"`

	// Email is an optional email address parameter for token scoping.
	Email string `json:"email,omitempty"`

	// CallbackURL overrides post-verification redirect URL.
	CallbackURL string `json:"callback_url,omitempty"`

	// NewUserCallbackURL overrides new-user redirect URL.
	NewUserCallbackURL string `json:"new_user_callback_url,omitempty"`

	// ErrorCallbackURL overrides error redirect URL.
	ErrorCallbackURL string `json:"error_callback_url,omitempty"`

	plugin.ExtraContainer
}

type VerifyMagicLinkResult struct {
	// User is the authenticated or newly created user entity.
	User *entity.User `json:"user"`

	// Session is the newly created active user session.
	Session *entity.Session `json:"session"`

	// IsNewUser reports whether a new user account was registered during verification.
	IsNewUser bool `json:"is_new_user"`

	// RedirectURL is the calculated destination URL for browser navigation.
	RedirectURL string `json:"redirect_url"`
}