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


-- | LIO support for the Simple web framework
--   
--   lio-simple adds LIO support for the Simple "framework-less" web
--   framework. Simple is minimalist, providing a lightweight base - the
--   most basic Simple app is little more than a WAI <a>Application</a>
--   with some routing logic. Everything else (e.g. authentication,
--   controllers, persistence, caching etc') is provided in composable
--   units, so you can include only the ones you need in your app, and
--   easily replace with your own components. LIO is an information flow
--   control library that lets you enforce various security policies,
--   including mandatory and discretionary access control.
--   
--   To get started, create an app skeleton with the `lio-simple` utility:
--   
--   <pre>
--   $ cabal install lio-simple
--   $ lio-simple my_app_name
--   $ cd my_app_name
--   $ cabal run
--   </pre>
@package lio-simple
@version 0.0.2.2


-- | Provides generic and HTTP Basic authentication.
module LIO.Web.Simple.Auth

-- | A middleware that uses HTTP basic authentication to authenticate a
--   request for a realm with the given username and password. The request
--   is rewritten with an <tt>X-User</tt> request header containing the
--   authenticated username before being passed to the next
--   <tt>application</tt>. Note that the HTTP basic authentication header
--   is only set if the executed app requests it, by setting the
--   <tt>X-Login</tt> response header (e.g., with <a>requestLogin</a>).
basicAuth :: Monad m => String -> (ByteString -> ByteString -> m Bool) -> SimpleMiddleware m

-- | Executes the app and if the app <a>Response</a> has header
--   <tt>X-Login</tt> and the user is not logged in, i.e., the
--   <tt>X-User</tt> request header is not present, execute the login
--   application.
handleAuth :: Monad m => SimpleApplication m -> SimpleMiddleware m

-- | Request authentication middleware to authenticate user
requestLogin :: Response

-- | Execute action with the current user's name. Otherwise, request that
--   the user authenticate.
withUserOrLogin :: Monad m => (ByteString -> ControllerT r m a) -> ControllerT r m a

-- | Get the current user.
currentUser :: Monad m => ControllerT r m (Maybe ByteString)


-- | This module exports a function <a>run</a> for creating a runner that
--   is used to run a <a>Web.Simple</a> <a>SimpleApplication</a> in the
--   <a>LIO</a> monad.
--   
--   The runner is only available to trusted code since we do not impose
--   any policy on how requests and responses should be handled. Middleware
--   should be used on both ends to ensure safety. This module provides
--   several such Middleware.
module LIO.Web.Simple.TCB

-- | An LIO simple aplpication is an <a>LIO</a> computation mapping a set
--   of privileges and request to a response. While privileges can be
--   provided in terms of a e.g., <tt>Reader</tt> monad, in certain cases
--   not having the privilege as part of the sate is cleaner.
type SimpleLIOApplication p l = Priv p -> SimpleApplication (LIO l)

-- | Simple LIO middleware.
type SimpleLIOMiddleware p l = SimpleLIOApplication p l -> SimpleLIOApplication p l

-- | Run an LIO web app wrapped by some middleware. Since web servers can
--   be quite messy it is important that you provide middleware to sanitize
--   responses to prevent data leakage.
--   
--   Since security properties vary across applications, we do not impose
--   any conditions on the requests and reponses. The latter can be
--   sanitized by supplying a middleware, while the former can simply be
--   baked-into the app (as <a>SimpleMiddleware</a>.
run :: Label l => Port -> Middleware -> SimpleApplication (LIO l) -> LIO l ()

-- | Same as <a>run</a>, but run <a>SimpleLIOApplication</a>s, i.e.,
--   applications that take privileges.
runP :: (PrivDesc l p, Label l) => Port -> Middleware -> Priv p -> SimpleLIOApplication p l -> LIO l ()

-- | Middleware that ensures the <a>Response</a> from the application is
--   readable by the client's browser (as determined by the result label of
--   the app computation and the label of the browser). If the response is
--   not readable by the browser, the middleware sends a 403 (unauthorized)
--   response instead.
browserLabelGuard :: MonadLIO l m => l -> SimpleMiddleware m

-- | Remove certain headers from the request.
removeRequestHeaders :: Monad m => [HeaderName] -> SimpleMiddleware m

-- | Remove certain headers from the response, e.g., Set-Cookie.
removeResponseHeaders :: Monad m => [HeaderName] -> SimpleMiddleware m

-- | Function to use to get a template. When the underlying monad is
--   <a>LIO</a>, it looks in the <tt>viewDirectory</tt> for the given file
--   name and compiles the file into a template.
--   
--   This function should be used only when the everything reachable from
--   the <tt>viewDirectory</tt> is public.
--   
--   To ensure that the function cannot be abused the function first cleans
--   up the file path: if it starts out with a <tt>..</tt>, we consider
--   this invalid as it can be used explore parts of the filesystem that
--   should otherwise be unaccessible. Similarly, we remove any <tt>.</tt>
--   from the path.
--   
--   Since this funciton does not use the 'lio-fs' filesystem
--   <tt>readFile</tt>, but rather the <a>IO</a> <tt>readFile</tt>, it
--   should not be exposed to untrusted code.
lioGetTemplateTCB :: Label l => FilePath -> LIO l Template


-- | This module defines several instances needed to use <a>LIO</a> as the
--   underlying monad with <a>Web.Simple</a>, the simple web framework.
--   Additionally, we provide some middleware for executing apps in a safe
--   manner.
--   
--   <a>LIO.Web.Simple.TCB</a> defines several functions that can be used
--   to execute <a>LIO</a> web applications with the Warp server.
module LIO.Web.Simple

-- | Parses a HTML form from the request body. It returns a list of
--   <a>Param</a>s as well as a list of <a>File</a>s, which are pairs
--   mapping the name of a <i>file</i> form field to a <a>FileInfo</a>
--   pointing to a temporary file with the contents of the
--   
--   Reads and returns the body of the HTTP request.
--   
--   Note: <tt>body</tt> function consumes the body from a Source IO
--   Bytestring. Since the <a>Request</a> constructor is exposed by
--   <a>Network.Wai.Internal</a>, it's important to disallow construction
--   of such values when considering untrusted code.
body :: Label l => LIOController l r ByteString

-- | Parses a HTML form from the request body. It returns a list of
--   <a>Param</a>s as well as a list of <a>File</a>s, which are pairs
--   mapping the name of a <i>file</i> form field to a <a>FileInfo</a>
--   pointing to a temporary file with the contents of the upload.
--   
--   Currently only tursted code can read the file.
parseForm :: Label l => LIOController l r ([Param], [(ByteString, FileInfo ByteString)])

-- | Middleware that ensures the <a>Response</a> from the application is
--   readable by the client's browser (as determined by the result label of
--   the app computation and the label of the browser). If the response is
--   not readable by the browser, the middleware sends a 403 (unauthorized)
--   response instead.
browserLabelGuard :: MonadLIO l m => l -> SimpleMiddleware m

-- | Remove certain headers from the request.
removeRequestHeaders :: Monad m => [HeaderName] -> SimpleMiddleware m

-- | Remove certain headers from the response, e.g., Set-Cookie.
removeResponseHeaders :: Monad m => [HeaderName] -> SimpleMiddleware m

-- | An LIO simple aplpication is an <a>LIO</a> computation mapping a set
--   of privileges and request to a response. While privileges can be
--   provided in terms of a e.g., <tt>Reader</tt> monad, in certain cases
--   not having the privilege as part of the sate is cleaner.
type SimpleLIOApplication p l = Priv p -> SimpleApplication (LIO l)

-- | Simple LIO middleware.
type SimpleLIOMiddleware p l = SimpleLIOApplication p l -> SimpleLIOApplication p l

-- | Controller with <a>LIO</a> as the underlying monad.
type LIOController l s = ControllerT s (LIO l)
instance Label l => MonadLIO l (ControllerT r (LIO l))


-- | This module exports several types that makes it easier to write LIO
--   web apps with DCLabels.
module LIO.Web.Simple.DCLabel
type DCController a = LIOController DCLabel a
type SimpleDCApplication = SimpleLIOApplication CNF DCLabel
type SimpleDCMiddleware = SimpleLIOMiddleware CNF DCLabel