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.
	//
	// Function:
	//   Called when generating and dispatching a new magic link verification token.
	//
	// Storage:
	//   Cache (Redis / In-Memory TTL) - Short-lived single-use magic link token.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - record: VerificationRecord containing identifier key, raw/hashed token, and expiration timestamp.
	//
	// Returns:
	//   - error: Nil on success, or database error.
	//
	// Example SQL:
	//   INSERT INTO verification_tokens (id, identifier, value, expires_at, created_at, updated_at) VALUES ($1, $2, $3, $4, $5, $6);
	//
	// Example Cache (Redis):
	//   err := rdb.Set(ctx, "magiclink:" + record.Identifier, bytes, ttl).Err()
	CreateVerificationValue(ctx context.Context, record *VerificationRecord) error

	// FindVerificationValue retrieves an active verification record matching the given identifier.
	//
	// Function:
	//   Used to inspect token validity without consuming it.
	//
	// Storage:
	//   Cache (Redis / In-Memory TTL) - Ephemeral token lookup.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - identifier: Composite token key (e.g. "magic-link-token:<hash>").
	//
	// Returns:
	//   - *VerificationRecord: Matching token record if found.
	//   - error: ErrInvalidToken if missing, or database error.
	//
	// Example SQL:
	//   SELECT id, identifier, value, expires_at, created_at, updated_at FROM verification_tokens WHERE identifier = $1 LIMIT 1;
	//
	// Example Cache (Redis):
	//   val, err := rdb.Get(ctx, "magiclink:" + identifier).Bytes()
	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.
	//
	// Function:
	//   Called during magic link verification endpoint to authenticate the user and consume the token.
	//
	// Storage:
	//   Cache (Redis GETDEL / Memory) - Atomic read-and-delete single-use token consumption.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - identifier: Composite token key.
	//
	// Returns:
	//   - *VerificationRecord: Consumed record if found and not expired.
	//   - error: ErrInvalidToken if missing, or ErrTokenExpired if passed expiry duration.
	//
	// Example SQL:
	//   DELETE FROM verification_tokens WHERE identifier = $1 AND expires_at > $2 RETURNING id, identifier, value, expires_at, created_at, updated_at;
	//
	// Example Cache (Redis):
	//   val, err := rdb.GetDel(ctx, "magiclink:" + identifier).Bytes()
	ConsumeVerificationValue(ctx context.Context, identifier string) (*VerificationRecord, error)

	// DeleteVerificationValue removes a verification record from persistent storage.
	//
	// Function:
	//   Called during cleanup or explicit revocation.
	//
	// Storage:
	//   Cache (Redis / In-Memory TTL) - Token key deletion.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - identifier: Token identifier key.
	//
	// Returns:
	//   - error: Nil on success.
	//
	// Example SQL:
	//   DELETE FROM verification_tokens WHERE identifier = $1;
	//
	// Example Cache (Redis):
	//   err := rdb.Del(ctx, "magiclink:" + identifier).Err()
	DeleteVerificationValue(ctx context.Context, identifier string) error

	// FindUserByEmail retrieves a user by their email address.
	//
	// Function:
	//   Called during magic link verification to find the target user.
	//
	// Storage:
	//   Database (GORM / SQL) - Relational user entity query.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - email: Recipient email address.
	//
	// Returns:
	//   - *entity.User: Matching user profile if found.
	//   - error: ErrUserNotFound if missing.
	//
	// Example SQL:
	//   SELECT id, email, name, email_verified, created_at, updated_at FROM users WHERE email = $1 LIMIT 1;
	FindUserByEmail(ctx context.Context, email string) (*entity.User, error)

	// CreateUser persists a new user entity in storage.
	//
	// Function:
	//   Called during magic link verification when sign-up is allowed for new email addresses.
	//
	// Storage:
	//   Database (GORM / SQL) - User entity insertion.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - user: User entity to persist.
	//
	// Returns:
	//   - *entity.User: Newly created user record.
	//   - error: Nil on success, or database error.
	//
	// Example SQL:
	//   INSERT INTO users (id, email, name, email_verified, created_at, updated_at) VALUES ($1, $2, $3, $4, $5, $6);
	CreateUser(ctx context.Context, user *entity.User) (*entity.User, error)

	// UpdateEmailVerified updates the email verification status for a specific user.
	//
	// Function:
	//   Called after verifying a magic link to set email_verified = true.
	//
	// Storage:
	//   Database (GORM / SQL) - User table update.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - userID: Target user ID.
	//   - verified: Boolean state.
	//
	// Returns:
	//   - error: Nil on success.
	//
	// Example SQL:
	//   UPDATE users SET email_verified = $1, updated_at = $2 WHERE id = $3;
	UpdateEmailVerified(ctx context.Context, userID string, verified bool) error

	// CreateSession initializes and persists an active user session.
	//
	// Function:
	//   Called after successful magic link verification to authenticate the user.
	//
	// Storage:
	//   Database (GORM / SQL) - Active session creation.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - session: Active session entity.
	//
	// Returns:
	//   - *entity.Session: Active session record.
	//   - error: Nil on success.
	//
	// Example SQL:
	//   INSERT INTO sessions (id, user_id, token, expires_at, created_at, updated_at) VALUES ($1, $2, $3, $4, $5, $6);
	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"`
}