{-# LANGUAGE ConstrainedClassMethods #-} {-# LANGUAGE FlexibleContexts #-} {-# LANGUAGE OverloadedStrings #-} {-# LANGUAGE PatternGuards #-} {-# LANGUAGE QuasiQuotes #-} {-# LANGUAGE Rank2Types #-} {-# LANGUAGE ScopedTypeVariables #-} {-# LANGUAGE TypeFamilies #-} -- | A Yesod plugin for Authentication via e-mail -- -- This plugin works out of the box by only setting a few methods on -- the type class that tell the plugin how to interoperate with your -- user data storage (your database). However, almost everything is -- customizeable by setting more methods on the type class. In -- addition, you can send all the form submissions via JSON and -- completely control the user's flow. -- -- This is a standard registration e-mail flow -- -- 1. A user registers a new e-mail address, and an e-mail is sent there -- 2. The user clicks on the registration link in the e-mail. Note that -- at this point they are actually logged in (without a -- password). That means that when they log out they will need to -- reset their password. -- 3. The user sets their password and is redirected to the site. -- 4. The user can now -- -- * logout and sign in -- * reset their password -- -- = Using JSON Endpoints -- -- We are assuming that you have declared auth route as follows -- -- @ -- /auth AuthR Auth getAuth -- @ -- -- If you are using a different route, then you have to adjust the -- endpoints accordingly. -- -- * Registration -- -- @ -- Endpoint: \/auth\/page\/email\/register -- Method: POST -- JSON Data: { -- "email": "myemail@domain.com", -- "password": "myStrongPassword" (optional) -- } -- @ -- -- * Forgot password -- -- @ -- Endpoint: \/auth\/page\/email\/forgot-password -- Method: POST -- JSON Data: { "email": "myemail@domain.com" } -- @ -- -- * Login -- -- @ -- Endpoint: \/auth\/page\/email\/login -- Method: POST -- JSON Data: { -- "email": "myemail@domain.com", -- "password": "myStrongPassword" -- } -- @ -- -- * Set new password -- -- @ -- Endpoint: \/auth\/page\/email\/set-password -- Method: POST -- JSON Data: { -- "new": "newPassword", -- "confirm": "newPassword", -- "current": "currentPassword" -- } -- @ -- -- Note that in the set password endpoint, the presence of the key -- "current" is dependent on how the 'needOldPassword' is defined in -- the instance for 'YesodAuthEmail'. module Yesod.Auth.Email ( -- * Plugin authEmail , YesodAuthEmail (..) , EmailCreds (..) , saltPass -- * Routes , loginR , registerR , forgotPasswordR , setpassR , verifyR , isValidPass -- * Types , Email , VerKey , VerUrl , SaltedPass , VerStatus , Identifier -- * Misc , loginLinkKey , setLoginLinkKey -- * Default handlers , defaultEmailLoginHandler , defaultRegisterHandler , defaultForgotPasswordHandler , defaultSetPasswordHandler -- * Default helpers , defaultRegisterHelper ) where import Control.Applicative ((<$>), (<*>)) import qualified Crypto.Hash as H import qualified Crypto.Nonce as Nonce import Data.Aeson.Types (Parser, Result (..), parseMaybe, withObject, (.:?)) import Data.ByteArray (convert) import Data.ByteString.Base16 as B16 import Data.Maybe (isJust) import Data.Text (Text) import qualified Data.Text as T import qualified Data.Text as TS import Data.Text.Encoding (decodeUtf8With, encodeUtf8) import qualified Data.Text.Encoding as TE import Data.Text.Encoding.Error (lenientDecode) import Data.Time (addUTCTime, getCurrentTime) import Safe (readMay) import System.IO.Unsafe (unsafePerformIO) import qualified Text.Email.Validate import Yesod.Auth import qualified Yesod.Auth.Message as Msg import qualified Yesod.Auth.Util.PasswordStore as PS import Yesod.Core import Yesod.Core.Types (TypedContent (TypedContent)) import Yesod.Form loginR, registerR, forgotPasswordR, setpassR :: AuthRoute loginR = PluginR "email" ["login"] registerR = PluginR "email" ["register"] forgotPasswordR = PluginR "email" ["forgot-password"] setpassR = PluginR "email" ["set-password"] verifyURLHasSetPassText :: Text verifyURLHasSetPassText = "has-set-pass" -- | -- -- @since 1.4.5 verifyR :: Text -> Text -> Bool -> AuthRoute -- FIXME verifyR eid verkey hasSetPass = PluginR "email" path where path = "verify":eid:verkey:(if hasSetPass then [verifyURLHasSetPassText] else []) type Email = Text type VerKey = Text type VerUrl = Text type SaltedPass = Text type VerStatus = Bool -- | An Identifier generalizes an email address to allow users to log in with -- some other form of credentials (e.g., username). -- -- Note that any of these other identifiers must not be valid email addresses. -- -- @since 1.2.0 type Identifier = Text -- | Data stored in a database for each e-mail address. data EmailCreds site = EmailCreds { emailCredsId :: AuthEmailId site , emailCredsAuthId :: Maybe (AuthId site) , emailCredsStatus :: VerStatus , emailCredsVerkey :: Maybe VerKey , emailCredsEmail :: Email } data ForgotPasswordForm = ForgotPasswordForm { _forgotEmail :: Text } data PasswordForm = PasswordForm { _passwordCurrent :: Text, _passwordNew :: Text, _passwordConfirm :: Text } data UserForm = UserForm { _userFormEmail :: Text } data UserLoginForm = UserLoginForm { _loginEmail :: Text, _loginPassword :: Text } class ( YesodAuth site , PathPiece (AuthEmailId site) , (RenderMessage site Msg.AuthMessage) ) => YesodAuthEmail site where type AuthEmailId site -- | Add a new email address to the database, but indicate that the address -- has not yet been verified. -- -- @since 1.1.0 addUnverified :: Email -> VerKey -> AuthHandler site (AuthEmailId site) -- | Similar to `addUnverified`, but comes with the registered password. -- -- The default implementation is just `addUnverified`, which ignores the password. -- -- You may override this to save the salted password to your database. -- -- @since 1.6.4 addUnverifiedWithPass :: Email -> VerKey -> SaltedPass -> AuthHandler site (AuthEmailId site) addUnverifiedWithPass email verkey _ = addUnverified email verkey -- | Send an email to the given address to verify ownership. -- -- @since 1.1.0 sendVerifyEmail :: Email -> VerKey -> VerUrl -> AuthHandler site () -- | Send an email to the given address to re-verify ownership in the case of -- a password reset. This can be used to send a different email when a user -- goes through the 'forgot password' flow as opposed to the 'account registration' -- flow. -- -- Default: Will call 'sendVerifyEmail', resulting in the same email getting sent -- for both registrations and password resets. -- -- @since 1.6.10 sendForgotPasswordEmail :: Email -> VerKey -> VerUrl -> AuthHandler site () sendForgotPasswordEmail = sendVerifyEmail -- | Get the verification key for the given email ID. -- -- @since 1.1.0 getVerifyKey :: AuthEmailId site -> AuthHandler site (Maybe VerKey) -- | Set the verification key for the given email ID. -- -- @since 1.1.0 setVerifyKey :: AuthEmailId site -> VerKey -> AuthHandler site () -- | Hash and salt a password -- -- Default: 'saltPass'. -- -- @since 1.4.20 hashAndSaltPassword :: Text -> AuthHandler site SaltedPass hashAndSaltPassword password = liftIO $ saltPass password -- | Verify a password matches the stored password for the given account. -- -- Default: Fetch a password with 'getPassword' and match using 'Yesod.Auth.Util.PasswordStore.verifyPassword'. -- -- @since 1.4.20 verifyPassword :: Text -> SaltedPass -> AuthHandler site Bool verifyPassword plain salted = return $ isValidPass plain salted -- | Verify the email address on the given account. -- -- __/Warning!/__ If you have persisted the @'AuthEmailId' site@ -- somewhere, this method should delete that key, or make it unusable -- in some fashion. Otherwise, the same key can be used multiple times! -- -- See . -- -- @since 1.1.0 verifyAccount :: AuthEmailId site -> AuthHandler site (Maybe (AuthId site)) -- | Get the salted password for the given account. -- -- @since 1.1.0 getPassword :: AuthId site -> AuthHandler site (Maybe SaltedPass) -- | Set the salted password for the given account. -- -- @since 1.1.0 setPassword :: AuthId site -> SaltedPass -> AuthHandler site () -- | Get the credentials for the given @Identifier@, which may be either an -- email address or some other identification (e.g., username). -- -- @since 1.2.0 getEmailCreds :: Identifier -> AuthHandler site (Maybe (EmailCreds site)) -- | Get the email address for the given email ID. -- -- @since 1.1.0 getEmail :: AuthEmailId site -> AuthHandler site (Maybe Email) -- | Generate a random alphanumeric string. -- -- @since 1.1.0 randomKey :: site -> IO VerKey randomKey _ = Nonce.nonce128urlT defaultNonceGen -- | Route to send user to after password has been set correctly. -- -- @since 1.2.0 afterPasswordRoute :: site -> Route site -- | Route to send user to after verification with a password -- -- @since 1.6.4 afterVerificationWithPass :: site -> Route site afterVerificationWithPass = afterPasswordRoute -- | Does the user need to provide the current password in order to set a -- new password? -- -- Default: if the user logged in via an email link do not require a password. -- -- @since 1.2.1 needOldPassword :: AuthId site -> AuthHandler site Bool needOldPassword aid' = do mkey <- lookupSession loginLinkKey case mkey >>= readMay . TS.unpack of Just (aidT, time) | Just aid <- fromPathPiece aidT, toPathPiece (aid `asTypeOf` aid') == toPathPiece aid' -> do now <- liftIO getCurrentTime return $ addUTCTime (60 * 30) time <= now _ -> return True -- | Check that the given plain-text password meets minimum security standards. -- -- Default: password is at least three characters. checkPasswordSecurity :: AuthId site -> Text -> AuthHandler site (Either Text ()) checkPasswordSecurity _ x | TS.length x >= 3 = return $ Right () | otherwise = return $ Left "Password must be at least three characters" -- | Response after sending a confirmation email. -- -- @since 1.2.2 confirmationEmailSentResponse :: Text -> AuthHandler site TypedContent confirmationEmailSentResponse identifier = do mr <- getMessageRender selectRep $ do provideJsonMessage (mr msg) provideRep $ authLayout $ do setTitleI Msg.ConfirmationEmailSentTitle [whamlet|

_{msg}|] where msg = Msg.ConfirmationEmailSent identifier -- | If a response is set, it will be used when an already-verified email -- tries to re-register. Otherwise, `confirmationEmailSentResponse` will be -- used. -- -- @since 1.6.4 emailPreviouslyRegisteredResponse :: MonadAuthHandler site m => Text -> Maybe (m TypedContent) emailPreviouslyRegisteredResponse _ = Nothing -- | Additional normalization of email addresses, besides standard canonicalization. -- -- Default: Lower case the email address. -- -- @since 1.2.3 normalizeEmailAddress :: site -> Text -> Text normalizeEmailAddress _ = TS.toLower -- | Handler called to render the login page. -- The default works fine, but you may want to override it in -- order to have a different DOM. -- -- Default: 'defaultEmailLoginHandler'. -- -- @since 1.4.17 emailLoginHandler :: (Route Auth -> Route site) -> WidgetFor site () emailLoginHandler = defaultEmailLoginHandler -- | Handler called to render the registration page. The -- default works fine, but you may want to override it in -- order to have a different DOM. -- -- Default: 'defaultRegisterHandler'. -- -- @since: 1.2.6 registerHandler :: AuthHandler site Html registerHandler = defaultRegisterHandler -- | Handler called to render the \"forgot password\" page. -- The default works fine, but you may want to override it in -- order to have a different DOM. -- -- Default: 'defaultForgotPasswordHandler'. -- -- @since: 1.2.6 forgotPasswordHandler :: AuthHandler site Html forgotPasswordHandler = defaultForgotPasswordHandler -- | Handler called to render the \"set password\" page. The -- default works fine, but you may want to override it in -- order to have a different DOM. -- -- Default: 'defaultSetPasswordHandler'. -- -- @since: 1.2.6 setPasswordHandler :: Bool -- ^ Whether the old password is needed. If @True@, a -- field for the old password should be presented. -- Otherwise, just two fields for the new password are -- needed. -> AuthHandler site TypedContent setPasswordHandler = defaultSetPasswordHandler -- | Helper that controls what happens after a user registration -- request is submitted. This method can be overridden to completely -- customize what happens during the user registration process, -- such as for handling additional fields in the registration form. -- -- The default implementation is in terms of 'defaultRegisterHelper'. -- -- @since: 1.6.9 registerHelper :: Route Auth -- ^ Where to sent the user in the event -- that registration fails -> AuthHandler site TypedContent registerHelper = defaultRegisterHelper False False -- | Helper that controls what happens after a forgot password -- request is submitted. As with `registerHelper`, this method can -- be overridden to customize the behavior when a user attempts -- to recover their password. -- -- The default implementation is in terms of 'defaultRegisterHelper'. -- -- @since: 1.6.9 passwordResetHelper :: Route Auth -- ^ Where to sent the user in the event -- that the password reset fails -> AuthHandler site TypedContent passwordResetHelper = defaultRegisterHelper True True authEmail :: (YesodAuthEmail m) => AuthPlugin m authEmail = AuthPlugin "email" dispatch emailLoginHandler where dispatch :: YesodAuthEmail m => Text -> [Text] -> AuthHandler m TypedContent dispatch "GET" ["register"] = getRegisterR >>= sendResponse dispatch "POST" ["register"] = postRegisterR >>= sendResponse dispatch "GET" ["forgot-password"] = getForgotPasswordR >>= sendResponse dispatch "POST" ["forgot-password"] = postForgotPasswordR >>= sendResponse dispatch "GET" ["verify", eid, verkey] = case fromPathPiece eid of Nothing -> notFound Just eid' -> getVerifyR eid' verkey False >>= sendResponse dispatch "GET" ["verify", eid, verkey, hasSetPass] = case fromPathPiece eid of Nothing -> notFound Just eid' -> getVerifyR eid' verkey (hasSetPass == verifyURLHasSetPassText) >>= sendResponse dispatch "POST" ["login"] = postLoginR >>= sendResponse dispatch "GET" ["set-password"] = getPasswordR >>= sendResponse dispatch "POST" ["set-password"] = postPasswordR >>= sendResponse dispatch _ _ = notFound getRegisterR :: YesodAuthEmail master => AuthHandler master Html getRegisterR = registerHandler -- | Default implementation of 'emailLoginHandler'. -- -- @since 1.4.17 defaultEmailLoginHandler :: YesodAuthEmail master => (Route Auth -> Route master) -> WidgetFor master () defaultEmailLoginHandler toParent = do (widget, enctype) <- generateFormPost loginForm [whamlet|

^{widget}