-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Authentication middleware that secures WAI application
--   
--   See README
@package wai-middleware-auth
@version 0.1.2.1

module Network.Wai.Middleware.Auth.Provider

-- | Core Authentication class, that allows for extensibility of the Auth
--   middleware created by <a>mkAuthMiddleware</a>. Most important function
--   is <a>handleLogin</a>, which implements the actual behavior of a
--   provider. It's function arguments in order:
--   
--   <ul>
--   <li><tt><tt>ap</tt></tt> - Current provider.</li>
--   <li><tt><a>Request</a></tt> - Request made to the login page</li>
--   <li><tt>[<a>Text</a>]</tt> - Url suffix, i.e. last part of the Url
--   split by <tt>'/'</tt> character, for instance <tt>["login",
--   "complete"]</tt> suffix in the example below.</li>
--   <li><tt><a>Render</a> <a>ProviderUrl</a></tt> - Url renderer. It takes
--   desired suffix as first argument and produces an absolute Url
--   renderer. It can further be used to generate provider urls, for
--   instance in Hamlet templates as will result in
--   <tt>"https://approot.com/_auth_middleware/providerName/login/complete?user=Hamlet"</tt>
--   or generate Urls for callbacks.<pre>@?{(ProviderUrl ["login",
--   "complete"], [("user", <a>Hamlet</a>)])} </pre></li>
--   <li><tt>(<a>UserIdentity</a> -&gt; <a>IO</a> <a>Response</a>)</tt> -
--   Action to call on a successfull login.</li>
--   <li><tt>(<a>Status</a> -&gt; <a>ByteString</a> -&gt; <a>IO</a>
--   <a>Response</a>)</tt> - Should be called in case of a failure with
--   login process by supplying a status and a short error message.</li>
--   </ul>
class AuthProvider ap

-- | Return a name for the provider. It will be used as a unique identifier
--   for this provider. Argument should not be evaluated, as there are many
--   places were <a>undefined</a> value is passed to this function.
getProviderName :: AuthProvider ap => ap -> Text

-- | Get info about the provider. It will be used in rendering the web page
--   with a list of providers.
getProviderInfo :: AuthProvider ap => ap -> ProviderInfo

-- | Handle a login request in a custom manner. Can be used to render a
--   login page with a form or redirect to some other authentication
--   service like OpenID or OAuth2.
handleLogin :: AuthProvider ap => ap -> Request -> [Text] -> Render ProviderUrl -> (UserIdentity -> IO Response) -> (Status -> ByteString -> IO Response) -> IO Response

-- | Generic authentication provider wrapper.
data Provider
[Provider] :: AuthProvider p => p -> Provider

-- | Data type for rendering Provider specific urls.
data ProviderUrl
ProviderUrl :: [Text] -> ProviderUrl

-- | Provider information used for rendering a page with list of supported
--   providers.
data ProviderInfo
ProviderInfo :: Text -> Text -> Text -> ProviderInfo
[providerTitle] :: ProviderInfo -> Text
[providerLogoUrl] :: ProviderInfo -> Text
[providerDescr] :: ProviderInfo -> Text

-- | Collection of supported providers.
type Providers = HashMap Text Provider

-- | Aeson parser for a provider with unique provider name (same as
--   returned by <a>getProviderName</a>)
type ProviderParser = (Text, Value -> Parser Provider)

-- | First argument is not evaluated and is only needed for restricting the
--   type.
mkProviderParser :: forall ap. (FromJSON ap, AuthProvider ap) => Proxy ap -> ProviderParser

-- | Parse configuration for providers from an <a>Object</a>.
parseProviders :: Object -> [ProviderParser] -> Result Providers

-- | Representation of a user for a particular <a>Provider</a>.
data AuthUser
AuthUser :: !UserIdentity -> !ByteString -> !Int64 -> AuthUser
[authUserIdentity] :: AuthUser -> !UserIdentity
[authProviderName] :: AuthUser -> !ByteString
[authLoginTime] :: AuthUser -> !Int64

-- | An arbitrary user identifer, eg. a username or an email address.
type UserIdentity = ByteString

-- | Create a url renderer for a provider.
mkRouteRender :: Maybe Text -> Text -> [Text] -> Render Provider

-- | Template for the providers page
providersTemplate :: Maybe Text -> Render Provider -> Providers -> Builder
instance Data.Aeson.Types.ToJSON.ToJSON Network.Wai.Middleware.Auth.Provider.ProviderInfo
instance Data.Aeson.Types.FromJSON.FromJSON Network.Wai.Middleware.Auth.Provider.ProviderInfo
instance GHC.Show.Show Network.Wai.Middleware.Auth.Provider.AuthUser
instance GHC.Generics.Generic Network.Wai.Middleware.Auth.Provider.AuthUser
instance GHC.Show.Show Network.Wai.Middleware.Auth.Provider.ProviderInfo
instance Data.Binary.Class.Binary Network.Wai.Middleware.Auth.Provider.AuthUser
instance Network.Wai.Middleware.Auth.Provider.AuthProvider Network.Wai.Middleware.Auth.Provider.Provider

module Network.Wai.Middleware.Auth.OAuth2

-- | General OAuth2 authentication <a>Provider</a>.
data OAuth2
OAuth2 :: Text -> Text -> Text -> Text -> Maybe [Text] -> ProviderInfo -> OAuth2
[oa2ClientId] :: OAuth2 -> Text
[oa2ClientSecret] :: OAuth2 -> Text
[oa2AuthorizeEndpoint] :: OAuth2 -> Text
[oa2AccessTokenEndpoint] :: OAuth2 -> Text
[oa2Scope] :: OAuth2 -> Maybe [Text]
[oa2ProviderInfo] :: OAuth2 -> ProviderInfo

-- | Aeson parser for <a>OAuth2</a> provider.
oAuth2Parser :: ProviderParser

-- | Used for validating proper url structure. Can be thrown by
--   <a>parseAbsoluteURI</a> and consequently by <a>handleLogin</a> for
--   <a>OAuth2</a> <a>Provider</a> instance.
data URIParseException
URIParseException :: URIParseError -> URIParseException

-- | Parse absolute URI and throw <a>URIParseException</a> in case it is
--   malformed
parseAbsoluteURI :: MonadThrow m => Text -> m URI
instance Data.Aeson.Types.ToJSON.ToJSON Network.Wai.Middleware.Auth.OAuth2.OAuth2
instance Data.Aeson.Types.FromJSON.FromJSON Network.Wai.Middleware.Auth.OAuth2.OAuth2
instance GHC.Show.Show Network.Wai.Middleware.Auth.OAuth2.URIParseException
instance GHC.Exception.Type.Exception Network.Wai.Middleware.Auth.OAuth2.URIParseException
instance Network.Wai.Middleware.Auth.Provider.AuthProvider Network.Wai.Middleware.Auth.OAuth2.OAuth2

module Network.Wai.Middleware.Auth.OAuth2.Google
data Google
Google :: Text -> [ByteString] -> OAuth2 -> Google
[googleAPIEmailEndpoint] :: Google -> Text
[googleEmailWhitelist] :: Google -> [ByteString]
[googleOAuth2] :: Google -> OAuth2

-- | Create a google authentication provider
mkGoogleProvider :: Text -> Text -> [ByteString] -> Maybe ProviderInfo -> Google

-- | Aeson parser for <a>Google</a> provider.
googleParser :: ProviderParser
instance GHC.Show.Show Network.Wai.Middleware.Auth.OAuth2.Google.GoogleEmail
instance Data.Aeson.Types.FromJSON.FromJSON Network.Wai.Middleware.Auth.OAuth2.Google.GoogleEmail
instance Network.Wai.Middleware.Auth.Provider.AuthProvider Network.Wai.Middleware.Auth.OAuth2.Google.Google
instance Data.Aeson.Types.FromJSON.FromJSON Network.Wai.Middleware.Auth.OAuth2.Google.Google

module Network.Wai.Middleware.Auth.OAuth2.Github

-- | Github authentication provider
data Github
Github :: Text -> Text -> [ByteString] -> OAuth2 -> Github
[githubAppName] :: Github -> Text
[githubAPIEmailEndpoint] :: Github -> Text
[githubEmailWhitelist] :: Github -> [ByteString]
[githubOAuth2] :: Github -> OAuth2

-- | Create a github authentication provider
mkGithubProvider :: Text -> Text -> Text -> [ByteString] -> Maybe ProviderInfo -> Github

-- | Aeson parser for <a>Github</a> provider.
githubParser :: ProviderParser
instance GHC.Show.Show Network.Wai.Middleware.Auth.OAuth2.Github.GithubEmail
instance Data.Aeson.Types.FromJSON.FromJSON Network.Wai.Middleware.Auth.OAuth2.Github.GithubEmail
instance Network.Wai.Middleware.Auth.Provider.AuthProvider Network.Wai.Middleware.Auth.OAuth2.Github.Github
instance Data.Aeson.Types.FromJSON.FromJSON Network.Wai.Middleware.Auth.OAuth2.Github.Github

module Network.Wai.Middleware.Auth

-- | Settings for creating the Auth middleware.
--   
--   To create a value, use <a>defaultAuthSettings</a> and then various
--   setter functions.
data AuthSettings

-- | Default middleware settings. See various setters in order to change
--   available settings
defaultAuthSettings :: AuthSettings

-- | Set the function to get client session key for encrypting cookie data.
--   
--   Default: <a>getDefaultKey</a>
setAuthKey :: IO Key -> AuthSettings -> AuthSettings

-- | The application root for this application.
--   
--   | Set the root for this Aplication. Required for external
--   Authentication providers to perform proper redirect.
--   
--   Default: use the APPROOT environment variable.
setAuthAppRootStatic :: Text -> AuthSettings -> AuthSettings

-- | More generalized version of <tt>setAuthApprootStatic</tt>.
setAuthAppRootGeneric :: (Request -> IO Text) -> AuthSettings -> AuthSettings

-- | Number of seconds to keep an authentication cookie active
--   
--   Default: 3600
setAuthSessionAge :: Int -> AuthSettings -> AuthSettings

-- | Set the cookie key.
--   
--   Default: "auth_state"
setAuthPrefix :: Text -> AuthSettings -> AuthSettings

-- | Set the cookie name.
--   
--   Default: "auth_state"
setAuthCookieName :: ByteString -> AuthSettings -> AuthSettings

-- | Set Authentication providers to be used.
--   
--   Default is empty.
setAuthProviders :: Providers -> AuthSettings -> AuthSettings

-- | Set a custom template that will be rendered for a providers page
--   
--   Default: <a>providersTemplate</a>
setAuthProvidersTemplate :: (Maybe Text -> Render Provider -> Providers -> Builder) -> AuthSettings -> AuthSettings

-- | Creates an Authentication middleware that will make sure application
--   is protected, thus allowing access only to users that go through an
--   authentication process with one of the available providers. If more
--   than one provider is specified, user will be directed to a page were
--   one can be chosen from a list.
mkAuthMiddleware :: AuthSettings -> IO Middleware

-- | Determine approot by:
--   
--   <ul>
--   <li>Respect the Host header and isSecure property, together with the
--   following de facto standards: x-forwarded-protocol, x-forwarded-ssl,
--   x-url-scheme, x-forwarded-proto, front-end-https. (Note: this list may
--   be updated at will in the future without doc updates.)</li>
--   </ul>
--   
--   Normally trusting headers in this way is insecure, however in the case
--   of approot, the worst that can happen is that the client will get an
--   incorrect URL. Note that this does not work for some situations, e.g.:
--   
--   <ul>
--   <li>Reverse proxies not setting one of the above mentioned
--   headers</li>
--   <li>Applications hosted somewhere besides the root of the domain
--   name</li>
--   <li>Reverse proxies that modify the host header</li>
--   </ul>
smartAppRoot :: Request -> Text

-- | Current version
waiMiddlewareAuthVersion :: Version

-- | Get the username for the current user.
--   
--   If called on a <tt>Request</tt> behind the middleware, should always
--   return a <tt>Just</tt> value.
getAuthUser :: Request -> Maybe AuthUser
instance GHC.Show.Show Network.Wai.Middleware.Auth.AuthState
instance GHC.Generics.Generic Network.Wai.Middleware.Auth.AuthState
instance Data.Binary.Class.Binary Network.Wai.Middleware.Auth.AuthState

module Network.Wai.Auth.Executable

-- | Construct a <tt>main</tt> function.
mkMain :: AuthConfig -> [ProviderParser] -> (Port -> Application -> IO ()) -> IO ()

-- | Read configuration from a yaml file with ability to use environment
--   variables. See <a>Data.Yaml.Config</a> module for details.
readAuthConfig :: FilePath -> IO AuthConfig

-- | Create an <a>Application</a> from a <a>Service</a>
serviceToApp :: Service -> IO Application

-- | Configuration for <tt>wai-auth</tt> executable and any other, that is
--   created using <a>mkMain</a>
data AuthConfig
AuthConfig :: Maybe Text -> Int -> Bool -> Bool -> Int -> SecretKey -> Service -> Object -> AuthConfig

-- | Root Url of the website, eg: <a>http://example.com</a> or
--   <a>https://example.com</a> It will be used to perform redirects back
--   from external authentication providers.
[configAppRoot] :: AuthConfig -> Maybe Text

-- | Port number. Default is 3000
[configAppPort] :: AuthConfig -> Int

-- | Require requests come in over a secure connection (determined via
--   headers). Will redirect to HTTPS if non-secure dedected. Default is
--   <tt>False</tt>
[configRequireTls] :: AuthConfig -> Bool

-- | Turn off authentication middleware, useful for testing. Default is
--   <tt>False</tt>
[configSkipAuth] :: AuthConfig -> Bool

-- | Duration of the session in seconds. Default is one hour (3600
--   seconds).
[configCookieAge] :: AuthConfig -> Int

-- | Secret key. Default is "client_session_key.aes"
[configSecretKey] :: AuthConfig -> SecretKey
[configService] :: AuthConfig -> Service
[configProviders] :: AuthConfig -> Object

-- | Configuration for a secret key that will be used to encrypt
--   authenticated user as client side cookie.
data SecretKey

-- | Path to a secret key file in binary form, if it is malformed or
--   doesn't exist it will be (re)created. If empty
--   "client_session_key.aes" name will be used
SecretKeyFile :: FilePath -> SecretKey

-- | Serialized and base64 encoded form of a secret key. Use
--   <a>encodeKey</a> to get a proper encoded form.
SecretKey :: Key -> SecretKey

-- | Available services.
data Service
ServiceFiles :: FileServer -> Service
ServiceProxy :: ReverseProxy -> Service

-- | Configuration for reverse proxy application.
data FileServer
FileServer :: FilePath -> Bool -> Bool -> FileServer

-- | Path to a folder containing files that will be served by this app.
[fsRootFolder] :: FileServer -> FilePath

-- | Redirect to the actual index file, not leaving the URL containing the
--   directory name
[fsRedirectToIndex] :: FileServer -> Bool

-- | Add a trailing slash to directory names
[fsAddTrailingSlash] :: FileServer -> Bool

-- | Configuration for reverse proxy application.
data ReverseProxy
ReverseProxy :: Text -> Int -> ReverseProxy

-- | Hostname of the webserver
[rpHost] :: ReverseProxy -> Text

-- | Port of the webserver
[rpPort] :: ReverseProxy -> Int

-- | Serialize and base64 encode a secret <a>Key</a>
encodeKey :: Key -> ByteString

-- | Decode a <a>Key</a> that is in a base64 encoded serialized form
decodeKey :: ByteString -> Either String Key
type Port = Int
