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


-- | Simple OAuth for http-client
--   
--   <i>Warning</i>: This software is pre 1.0 and thus its API may change
--   very dynamically while updating only minor versions. This package will
--   follow the PVP once it reaches version 1.0.
--   
--   OAuth is a popular protocol allowing servers to offer resources owned
--   by some user to a series of authorized clients securely. For instance,
--   OAuth lets Twitter provide access to a user's private tweets to the
--   Twitter client registered on their phone.
--   
--   <tt>oauthenticated</tt> is a Haskell library implementing OAuth
--   protocols atop the minimalistic <tt>http-client</tt> HTTP client
--   library extracted from <tt>http-conduit</tt>. <a>Network.OAuth</a>
--   offers simple functions for signing
--   <a>Network.HTTP.Client.Request</a>s along with tools for
--   <a>Network.OAuth.Cred</a>ential management and
--   <a>Network.OAuth.Server</a> configuration. <a>Network.OAuth.Simple</a>
--   provides a slightly more heavy-weight interface which manages the
--   necessary state and configuration using a monad transformer stack.
--   
--   There's also an implementation of OAuth's three-legged credential
--   acquisition protocol built atop the <a>Network.OAuth</a> API. This can
--   be handled in both conformant and old-style modes: conformant will
--   reject server responses which are not conformant with RFC 5849 (which
--   builds atop community version OAuth 1.0a) while old-style better
--   allows for less-than-compliant servers. See
--   <a>Network.OAuth.Types.Params.Version</a> for more details.
--   
--   Currently <tt>oauthenticated</tt> only supports OAuth 1.0 and is in
--   alpha. OAuth 2.0 support is a potential goal, but it's unclear if it
--   can be transparently supported at a similar level of abstraction.
@package oauthenticated
@version 0.2.1.0


-- | Credentials, <a>Cred</a>s, are built from <a>Token</a>s,
--   public/private key pairs, and come in 3 varieties.
--   
--   <ul>
--   <li><a>Client</a>: Represents a particular client or consumer, used as
--   part of every transaction that client signs.</li>
--   <li><a>Temporary</a>: Resource token representing a short-lived grant
--   to access a restricted set of server resources on behalf of the user.
--   Typically used as part of a authorization negotiation protocol.</li>
--   <li><a>Permanent</a>: Resource token representing a long-lived grant
--   to access an authorized set of server resources on behalf of the user.
--   Outside of access negotiation this is the most common kind of resource
--   <a>Token</a>.</li>
--   </ul>
module Network.OAuth.Types.Credentials

-- | <a>Token</a>s are public, private key pairs and come in many
--   varieties, <a>Client</a>, <a>Temporary</a>, and <a>Permanent</a>.
data Token ty
Token :: {-# UNPACK #-} !Key -> {-# UNPACK #-} !Secret -> Token ty

-- | <a>Token</a> <a>Key</a>s are public keys which allow a server to
--   uniquely identify a particular <a>Token</a>.
type Key = ByteString

-- | <a>Token</a> <a>Secret</a>s are private keys which the <a>Token</a>
--   uses for cryptographic purposes.
type Secret = ByteString

-- | <a>Client</a> <a>Cred</a>entials and <a>Token</a>s are assigned to a
--   particular client by the server and are used for all requests sent by
--   that client. They form the core component of resource specific
--   credentials.
data Client

-- | <a>Temporary</a> <a>Token</a>s and <a>Cred</a>entials are created
--   during authorization protocols and are rarely meant to be kept for
--   more than a few minutes. Typically they are authorized to access only
--   a very select set of server resources. During "three-legged
--   authorization" in OAuth 1.0 they are used to generate the
--   authorization request URI the client sends and, after that, in the
--   <a>Permanent</a> <a>Token</a> request.
data Temporary

-- | <a>Permanent</a> <a>Token</a>s and <a>Cred</a>entials are the primary
--   means of accessing server resources. They must be maintained by the
--   client for each user who authorizes that client to access resources on
--   their behalf.
data Permanent
class ResourceToken tk

-- | Parses a <tt>www-form-urlencoded</tt> stream to produce a <a>Token</a>
--   if possible. The first result value is whether or not the token data
--   is OAuth 1.0a compatible.
--   
--   <pre>
--   &gt;&gt;&gt; fromUrlEncoded "oauth_token=key&amp;oauth_token_secret=secret"
--   Just (False, Token "key" "secret")
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fromUrlEncoded "oauth_token=key&amp;oauth_token_secret=secret&amp;oauth_callback_confirmed=true"
--   Just (True, Token "key" "secret")
--   </pre>
fromUrlEncoded :: ByteString -> Maybe (Bool, Token ty)

-- | <a>Cred</a>entials pair a <a>Client</a> <a>Token</a> and either a
--   <a>Temporary</a> or <a>Permanent</a> token corresponding to a
--   particular set of user resources on the server.
data Cred ty
clientCred :: Token Client -> Cred Client
temporaryCred :: Token Temporary -> Cred Client -> Cred Temporary
permanentCred :: Token Permanent -> Cred Client -> Cred Permanent
upgradeCred :: ResourceToken tk => Token tk -> Cred tk' -> Cred tk

-- | Lens on the key component of a <a>Token</a>.
key :: Functor f => (Key -> f Key) -> Token ty -> f (Token ty)

-- | Lens on the key secret component of a <a>Token</a>.
secret :: Functor f => (Secret -> f Secret) -> Token ty -> f (Token ty)

-- | A lens on the client <a>Token</a> in any <a>Cred</a>.
clientToken :: Functor f => (Token Client -> f (Token Client)) -> Cred ty -> f (Cred ty)

-- | A lens focused on the resource <a>Token</a> when available. The only
--   instances of <a>ResourceToken</a> are <a>Temporary</a> and
--   <a>Permanent</a>. This can be used to upgrade <a>Temporary</a>
--   <a>Cred</a>s to <a>Permanent</a> <a>Cred</a>s.
resourceToken :: (ResourceToken ty, ResourceToken ty', Functor f) => (Token ty -> f (Token ty')) -> Cred ty -> f (Cred ty')

-- | OAuth assumes that, by default, any credential has a resource
--   <a>Token</a> that is by default completely blank. In this way we can
--   talk about the resource <a>Token</a> of even <a>Client</a>
--   <a>Cred</a>s.
--   
--   <pre>
--   &gt;&gt;&gt; getResourceTokenDef (clientCred $ Token "key" "secret")
--   Token "" ""
--   </pre>
getResourceTokenDef :: Cred ty -> Token ty

-- | Produce a <a>signingKey</a> from a set of credentials. This is a URL
--   encoded string built from the client secret and the token secret.
--   
--   If no token secret exists then the blank string is used.
--   
--   <pre>
--   \secret -&gt; signingKey (clientCred $ Token "key" secret) == (pctEncode secret &lt;&gt; "&amp;" &lt;&gt; "")
--   </pre>
signingKey :: Cred ty -> ByteString
instance Data.Data.Data ty => Data.Data.Data (Network.OAuth.Types.Credentials.Cred ty)
instance GHC.Classes.Ord (Network.OAuth.Types.Credentials.Cred ty)
instance GHC.Classes.Eq (Network.OAuth.Types.Credentials.Cred ty)
instance GHC.Show.Show (Network.OAuth.Types.Credentials.Cred ty)
instance Data.Data.Data ty => Data.Data.Data (Network.OAuth.Types.Credentials.Token ty)
instance GHC.Classes.Ord (Network.OAuth.Types.Credentials.Token ty)
instance GHC.Classes.Eq (Network.OAuth.Types.Credentials.Token ty)
instance GHC.Show.Show (Network.OAuth.Types.Credentials.Token ty)
instance Data.Data.Data Network.OAuth.Types.Credentials.Permanent
instance Data.Data.Data Network.OAuth.Types.Credentials.Temporary
instance Data.Data.Data Network.OAuth.Types.Credentials.Client
instance Network.OAuth.Types.Credentials.ResourceToken Network.OAuth.Types.Credentials.Temporary
instance Network.OAuth.Types.Credentials.ResourceToken Network.OAuth.Types.Credentials.Permanent
instance Data.Aeson.Types.FromJSON.FromJSON (Network.OAuth.Types.Credentials.Token ty)
instance Data.Aeson.Types.ToJSON.ToJSON (Network.OAuth.Types.Credentials.Token ty)


-- | <i>OAuth Parameters</i>
--   
--   OAuth 1.0 operates by creating a set of "oauth parameters" here called
--   <a>Oa</a> which augment a request with OAuth specific metadata. They
--   may be used to augment the request by one of several
--   <tt>ParameterMethods</tt>.
module Network.OAuth.Types.Params

-- | The OAuth spec suggest that the OAuth parameter be passed via the
--   <tt>Authorization</tt> header, but allows for other methods of
--   transmission (see section "3.5. Parameter Transmission") so we select
--   the 'Server'\'s preferred method with this type.
data ParameterMethod

-- | Place the <a>Oa</a> parameters in the <tt>Authorization</tt> HTTP
--   header.
AuthorizationHeader :: ParameterMethod

-- | Augment the <tt>www-form-urlencoded</tt> request body with <a>Oa</a>
--   parameters.
RequestEntityBody :: ParameterMethod

-- | Augment the <tt>www-form-urlencoded</tt> query string with <a>Oa</a>
--   parameters.
QueryString :: ParameterMethod

-- | OAuth culminates in the creation of the <tt>oauth_signature</tt> which
--   signs and authenticates the request using the secret components of a
--   particular OAuth <a>Cred</a>.
--   
--   Several methods exist for generating these signatures, the most
--   popular being <a>HmacSha1</a>.
data SignatureMethod
HmacSha1 :: SignatureMethod
Plaintext :: SignatureMethod

-- | OAuth has progressed through several versions since its inception. In
--   particular, there are two community editions "OAuth Core 1.0" (2007)
--   and "OAuth Core 1.0a" (2009) along with the IETF Official version RFC
--   5849 (2010) which is confusingly named "OAuth 1.0".
--   
--   /Servers which only implement the obsoleted community edition "OAuth
--   Core 1.0" are susceptible to a session fixation attack./
--   
--   If at all possible, choose the RFC 5849 version (the <a>OAuth1</a>
--   value) as it is the modern standard. Some servers may only be
--   compliant with an earlier OAuth version---this should be tested
--   against each server, in particular the protocols defined in
--   <a>Network.OAuth.ThreeLegged</a>.
data Version

-- | OAuth Core 1.0 Community Edition
OAuthCommunity1 :: Version

-- | OAuth Core 1.0 Community Edition, Revision A
OAuthCommunity1a :: Version

-- | RFC 5849
OAuth1 :: Version

-- | All three OAuth 1.0 versions confusingly report the same version
--   number.

-- | When performing the second leg of the three-leg token request
--   workflow, the user must pass the <tt>oauth_verifier</tt> code back to
--   the client. In order to ensure that this protocol is secure, OAuth
--   demands that the client associates this "callback method" with the
--   temporary credentials generated for the workflow. This <a>Callback</a>
--   method may be a URL where the parameters are returned to or the string
--   <tt>"oob"</tt> which indicates that the user is responsible for
--   returning the <tt>oauth_verifier</tt> to the client <a>OutOfBand</a>.
data Callback
OutOfBand :: Callback
Callback :: Request -> Callback

-- | Prints out in Epoch time format, a printed integer

-- | An Epoch time format timestamp.
newtype Timestamp
Timestamp :: UTCTime -> Timestamp

-- | Create a <a>Timestamp</a> deterministically from a POSIX Epoch Time.
timestampFromSeconds :: Integer -> Timestamp

-- | Prints out in Epoch time format, a printed integer

-- | The <a>Server</a> information contains details which parameterize how
--   a particular server wants to interpret OAuth requests.
data Server
Server :: ParameterMethod -> SignatureMethod -> Version -> Server
[parameterMethod] :: Server -> ParameterMethod
[signatureMethod] :: Server -> SignatureMethod
[oAuthVersion] :: Server -> Version

-- | The default <a>Server</a> parameterization uses OAuth recommended
--   parameters.
defaultServer :: Server

-- | A <a>Verifier</a> is produced when a user authorizes a set of
--   <a>Temporary</a> <a>Cred</a>s. Using the <a>Verifier</a> allows the
--   client to request <a>Permanent</a> <a>Cred</a>s.
type Verifier = ByteString

-- | Some special OAuth requests use extra <tt>oauth_*</tt> parameters. For
--   example, when requesting a temporary credential, it's necessary that a
--   <tt>oauth_callback</tt> parameter be specified.
--   <tt>WorkflowParams</tt> allows these extra parameters to be specified.
data Workflow

-- | No special OAuth parameters needed
Standard :: Workflow
TemporaryTokenRequest :: Callback -> Workflow

-- | Includes the <tt>oauth_verifier</tt>
PermanentTokenRequest :: ByteString -> Workflow

-- | The <a>OaPin</a> is a set of impure OAuth parameters which are
--   generated for each request in order to ensure uniqueness and
--   temporality.
data OaPin
OaPin :: Timestamp -> ByteString -> OaPin
[timestamp] :: OaPin -> Timestamp
[nonce] :: OaPin -> ByteString

-- | An "empty" pin useful for testing. This <a>OaPin</a> is referentially
--   transparent and thus has none of the necessary security features---it
--   should <i>never</i> be used in an actual transaction!
emptyPin :: OaPin

-- | Creates a new, unique, unpredictable <a>OaPin</a>. This should be used
--   quickly as dependent on the OAuth server settings it may expire.
freshPin :: (MonadRandom m, MonadIO m) => m OaPin

-- | Uses <a>emptyPin</a> to create an empty set of params <a>Oa</a>.
emptyOa :: Cred ty -> Oa ty

-- | Uses <a>freshPin</a> to create a fresh, default set of params
--   <a>Oa</a>.
freshOa :: (MonadRandom m, MonadIO m) => Cred ty -> m (Oa ty)

-- | The <a>Oa</a> parameters include all the OAuth information specific to
--   a single request. They are not sufficient information by themselves to
--   generate the entire OAuth request but instead must be augmented with
--   <a>Server</a> information.
data Oa ty
Oa :: Cred ty -> Workflow -> OaPin -> Oa ty
[credentials] :: Oa ty -> Cred ty
[workflow] :: Oa ty -> Workflow
[pin] :: Oa ty -> OaPin
instance GHC.Show.Show (Network.OAuth.Types.Params.Oa ty)
instance Data.Data.Data Network.OAuth.Types.Params.OaPin
instance GHC.Classes.Ord Network.OAuth.Types.Params.OaPin
instance GHC.Classes.Eq Network.OAuth.Types.Params.OaPin
instance GHC.Show.Show Network.OAuth.Types.Params.OaPin
instance GHC.Show.Show Network.OAuth.Types.Params.Workflow
instance Data.Data.Data Network.OAuth.Types.Params.Server
instance GHC.Classes.Ord Network.OAuth.Types.Params.Server
instance GHC.Classes.Eq Network.OAuth.Types.Params.Server
instance GHC.Show.Show Network.OAuth.Types.Params.Server
instance Data.Data.Data Network.OAuth.Types.Params.Timestamp
instance GHC.Classes.Ord Network.OAuth.Types.Params.Timestamp
instance GHC.Classes.Eq Network.OAuth.Types.Params.Timestamp
instance GHC.Show.Show Network.OAuth.Types.Params.Timestamp
instance Data.Data.Data Network.OAuth.Types.Params.Version
instance GHC.Classes.Ord Network.OAuth.Types.Params.Version
instance GHC.Classes.Eq Network.OAuth.Types.Params.Version
instance GHC.Show.Show Network.OAuth.Types.Params.Version
instance Data.Data.Data Network.OAuth.Types.Params.SignatureMethod
instance GHC.Classes.Ord Network.OAuth.Types.Params.SignatureMethod
instance GHC.Classes.Eq Network.OAuth.Types.Params.SignatureMethod
instance GHC.Show.Show Network.OAuth.Types.Params.SignatureMethod
instance Data.Data.Data Network.OAuth.Types.Params.ParameterMethod
instance GHC.Classes.Ord Network.OAuth.Types.Params.ParameterMethod
instance GHC.Classes.Eq Network.OAuth.Types.Params.ParameterMethod
instance GHC.Show.Show Network.OAuth.Types.Params.ParameterMethod
instance Network.HTTP.Types.QueryLike.QueryValueLike Network.OAuth.Types.Params.Timestamp
instance GHC.Show.Show Network.OAuth.Types.Params.Callback
instance Network.HTTP.Types.QueryLike.QueryValueLike Network.OAuth.Types.Params.Callback
instance Network.HTTP.Types.QueryLike.QueryValueLike Network.OAuth.Types.Params.Version
instance Network.HTTP.Types.QueryLike.QueryValueLike Network.OAuth.Types.Params.SignatureMethod


-- | Signing forms the core process for OAuth. Given a <a>Request</a> about
--   to be sent, <a>Server</a> parameters, and a full <a>Oa</a> we append a
--   set of parameters to the <a>Request</a> which turns it into a signed
--   OAuth request.
module Network.OAuth.Signing

-- | Sign a request with a fresh set of parameters.
oauth :: (MonadIO m, MonadRandom m) => Cred ty -> Server -> Request -> m Request

-- | Sign a request given generated parameters
sign :: Oa ty -> Server -> Request -> Request
makeSignature :: SignatureMethod -> ByteString -> ByteString -> ByteString

-- | Augments whatever component of the <a>Request</a> is specified by
--   <a>ParameterMethod</a> with one built from the apropriate OAuth
--   parameters (passed as a <a>Query</a>).
--   
--   Currently this actually <i>replaces</i> the <tt>Authorization</tt>
--   header if one exists. This may be a bad idea if the <tt>realm</tt>
--   parameter is pre-set, perhaps.
--   
--   TODO: Parse <tt>Authorization</tt> header and augment it.
--   
--   Currently this actually <i>replaces</i> the entity body if one exists.
--   This is definitely just me being lazy.
--   
--   TODO: Try to parse entity body and augment it.
augmentRequest :: ParameterMethod -> Query -> Request -> Request
canonicalBaseString :: Oa ty -> Server -> Request -> ByteString
canonicalParams :: Oa ty -> Server -> Request -> ByteString
oauthParams :: Oa ty -> Server -> Query
canonicalUri :: Request -> ByteString

-- | Queries a <a>Request</a> body and tries to interpret it as a set of
--   OAuth valid parameters. It makes the assumption that if the body type
--   is a streaming variety or impure then it is <i>not</i> a set of OAuth
--   parameters--- dropping this assumption would prevent this from being
--   pure.
bodyParams :: Request -> Query
queryParams :: Request -> Query


-- | OAuth tools for using <tt>http-client</tt> for authenticated requests.
--   
--   The functions here form the simplest basis for sending OAuthenticated
--   <a>Request</a>s. In order to generate credentials according to the
--   OAuth "three-legged workflow" use actions in the
--   <a>Network.OAuth.ThreeLegged</a> module.
module Network.OAuth

-- | Sign a request with a fresh set of parameters. Uses <tt>MonadRandom
--   IO</tt>, getting new entropy for each signing and thus is potentially
--   <i>dangerous</i> if used too frequently. In almost all cases,
--   <a>oauth</a> should be used instead with a suitably seeded PRNG.
oauthSimple :: Cred ty -> Server -> Request -> IO Request

-- | Sign a request with a fresh set of parameters.
oauth :: (MonadIO m, MonadRandom m) => Cred ty -> Server -> Request -> m Request

-- | Sign a request given generated parameters
sign :: Oa ty -> Server -> Request -> Request

-- | Uses <a>emptyPin</a> to create an empty set of params <a>Oa</a>.
emptyOa :: Cred ty -> Oa ty

-- | Uses <a>freshPin</a> to create a fresh, default set of params
--   <a>Oa</a>.
freshOa :: (MonadRandom m, MonadIO m) => Cred ty -> m (Oa ty)

-- | An "empty" pin useful for testing. This <a>OaPin</a> is referentially
--   transparent and thus has none of the necessary security features---it
--   should <i>never</i> be used in an actual transaction!
emptyPin :: OaPin

-- | Creates a new, unique, unpredictable <a>OaPin</a>. This should be used
--   quickly as dependent on the OAuth server settings it may expire.
freshPin :: (MonadRandom m, MonadIO m) => m OaPin

-- | <a>Token</a>s are public, private key pairs and come in many
--   varieties, <a>Client</a>, <a>Temporary</a>, and <a>Permanent</a>.
data Token ty
Token :: {-# UNPACK #-} !Key -> {-# UNPACK #-} !Secret -> Token ty

-- | <a>Cred</a>entials pair a <a>Client</a> <a>Token</a> and either a
--   <a>Temporary</a> or <a>Permanent</a> token corresponding to a
--   particular set of user resources on the server.
data Cred ty

-- | <a>Client</a> <a>Cred</a>entials and <a>Token</a>s are assigned to a
--   particular client by the server and are used for all requests sent by
--   that client. They form the core component of resource specific
--   credentials.
data Client

-- | <a>Temporary</a> <a>Token</a>s and <a>Cred</a>entials are created
--   during authorization protocols and are rarely meant to be kept for
--   more than a few minutes. Typically they are authorized to access only
--   a very select set of server resources. During "three-legged
--   authorization" in OAuth 1.0 they are used to generate the
--   authorization request URI the client sends and, after that, in the
--   <a>Permanent</a> <a>Token</a> request.
data Temporary

-- | <a>Permanent</a> <a>Token</a>s and <a>Cred</a>entials are the primary
--   means of accessing server resources. They must be maintained by the
--   client for each user who authorizes that client to access resources on
--   their behalf.
data Permanent
clientCred :: Token Client -> Cred Client
temporaryCred :: Token Temporary -> Cred Client -> Cred Temporary
permanentCred :: Token Permanent -> Cred Client -> Cred Permanent

-- | Parses a <tt>www-form-urlencoded</tt> stream to produce a <a>Token</a>
--   if possible. The first result value is whether or not the token data
--   is OAuth 1.0a compatible.
--   
--   <pre>
--   &gt;&gt;&gt; fromUrlEncoded "oauth_token=key&amp;oauth_token_secret=secret"
--   Just (False, Token "key" "secret")
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fromUrlEncoded "oauth_token=key&amp;oauth_token_secret=secret&amp;oauth_callback_confirmed=true"
--   Just (True, Token "key" "secret")
--   </pre>
fromUrlEncoded :: ByteString -> Maybe (Bool, Token ty)

-- | The <a>Server</a> information contains details which parameterize how
--   a particular server wants to interpret OAuth requests.
data Server
Server :: ParameterMethod -> SignatureMethod -> Version -> Server
[parameterMethod] :: Server -> ParameterMethod
[signatureMethod] :: Server -> SignatureMethod
[oAuthVersion] :: Server -> Version

-- | The default <a>Server</a> parameterization uses OAuth recommended
--   parameters.
defaultServer :: Server

-- | The OAuth spec suggest that the OAuth parameter be passed via the
--   <tt>Authorization</tt> header, but allows for other methods of
--   transmission (see section "3.5. Parameter Transmission") so we select
--   the 'Server'\'s preferred method with this type.
data ParameterMethod

-- | Place the <a>Oa</a> parameters in the <tt>Authorization</tt> HTTP
--   header.
AuthorizationHeader :: ParameterMethod

-- | Augment the <tt>www-form-urlencoded</tt> request body with <a>Oa</a>
--   parameters.
RequestEntityBody :: ParameterMethod

-- | Augment the <tt>www-form-urlencoded</tt> query string with <a>Oa</a>
--   parameters.
QueryString :: ParameterMethod

-- | OAuth culminates in the creation of the <tt>oauth_signature</tt> which
--   signs and authenticates the request using the secret components of a
--   particular OAuth <a>Cred</a>.
--   
--   Several methods exist for generating these signatures, the most
--   popular being <a>HmacSha1</a>.
data SignatureMethod
HmacSha1 :: SignatureMethod
Plaintext :: SignatureMethod

-- | OAuth has progressed through several versions since its inception. In
--   particular, there are two community editions "OAuth Core 1.0" (2007)
--   and "OAuth Core 1.0a" (2009) along with the IETF Official version RFC
--   5849 (2010) which is confusingly named "OAuth 1.0".
--   
--   /Servers which only implement the obsoleted community edition "OAuth
--   Core 1.0" are susceptible to a session fixation attack./
--   
--   If at all possible, choose the RFC 5849 version (the <a>OAuth1</a>
--   value) as it is the modern standard. Some servers may only be
--   compliant with an earlier OAuth version---this should be tested
--   against each server, in particular the protocols defined in
--   <a>Network.OAuth.ThreeLegged</a>.
data Version

-- | OAuth Core 1.0 Community Edition
OAuthCommunity1 :: Version

-- | OAuth Core 1.0 Community Edition, Revision A
OAuthCommunity1a :: Version

-- | RFC 5849
OAuth1 :: Version


-- | The "Three-legged OAuth" protocol implementing RFC 5849's
--   <i>Redirection-Based Authorization</i>.
module Network.OAuth.ThreeLegged

-- | Data parameterizing the "Three-legged OAuth" redirection-based
--   authorization protocol. These parameters cover the protocol as
--   described in the community editions <i>OAuth Core 1.0</i> and <i>OAuth
--   Core 1.0a</i> as well as RFC 5849.
data ThreeLegged
ThreeLegged :: Request -> Request -> Request -> Callback -> ThreeLegged

-- | Base <tt>Request</tt> for the "endpoint used by the client to obtain a
--   set of <tt>Temporary</tt> <tt>Cred</tt>entials" in the form of a
--   <tt>Temporary</tt> <tt>Token</tt>. This request is automatically
--   instantiated and performed during the first leg of the
--   <a>ThreeLegged</a> authorization protocol.
[temporaryTokenRequest] :: ThreeLegged -> Request

-- | Base <tt>Request</tt> for the "endpoint to which the resource owner is
--   redirected to grant authorization". This request must be performed by
--   the user granting token authorization to the client. Transmitting the
--   parameters of this request to the user is out of scope of
--   <tt>oauthenticated</tt>, but functions are provided to make it easier.
[resourceOwnerAuthorization] :: ThreeLegged -> Request

-- | Base <tt>Request</tt> for the "endpoint used by the client to request
--   a set of token credentials using the set of <tt>Temporary</tt>
--   <tt>Cred</tt>entials". This request is also instantiated and performed
--   by <tt>oauthenticated</tt> in order to produce a <tt>Permanent</tt>
--   <tt>Token</tt>.
[permanentTokenRequest] :: ThreeLegged -> Request

-- | The <tt>Callback</tt> parameter configures how the user is intended to
--   communicate the <tt>Verifier</tt> back to the client.
[callback] :: ThreeLegged -> Callback

-- | Convenience method for creating a <a>ThreeLegged</a> configuration
--   from a trio of URLs and a <tt>Callback</tt>. Returns <a>Nothing</a> if
--   one of the callback URLs could not be parsed correctly.
parseThreeLegged :: String -> String -> String -> Callback -> Maybe ThreeLegged

-- | When performing the second leg of the three-leg token request
--   workflow, the user must pass the <tt>oauth_verifier</tt> code back to
--   the client. In order to ensure that this protocol is secure, OAuth
--   demands that the client associates this "callback method" with the
--   temporary credentials generated for the workflow. This <a>Callback</a>
--   method may be a URL where the parameters are returned to or the string
--   <tt>"oob"</tt> which indicates that the user is responsible for
--   returning the <tt>oauth_verifier</tt> to the client <a>OutOfBand</a>.
data Callback
OutOfBand :: Callback
Callback :: Request -> Callback

-- | A <a>Verifier</a> is produced when a user authorizes a set of
--   <a>Temporary</a> <a>Cred</a>s. Using the <a>Verifier</a> allows the
--   client to request <a>Permanent</a> <a>Cred</a>s.
type Verifier = ByteString

-- | Returns the raw result if the <a>Response</a> could not be parsed as a
--   valid <a>Token</a>. Importantly, in RFC 5849 compliant modes this
--   requires that the token response includes
--   <tt>callback_confirmed=true</tt>. See also
--   <a>requestTemporaryTokenRaw</a>.
--   
--   Throws <a>HttpException</a>s.
requestTemporaryToken :: (MonadIO m, MonadRandom m) => Cred Client -> Server -> ThreeLegged -> Manager -> m (Response (Either ByteString (Token Temporary)))

-- | Produce a <a>URI</a> which the user should be directed to in order to
--   authorize a set of <tt>Temporary</tt> <tt>Cred</tt>s.
buildAuthorizationUrl :: Cred Temporary -> ThreeLegged -> URI

-- | Returns <a>Nothing</a> if the response could not be decoded as a
--   <tt>Token</tt>. See also <a>requestPermanentTokenRaw</a>.
--   
--   Throws <a>HttpException</a>s.
requestPermanentToken :: (MonadIO m, MonadRandom m) => Cred Temporary -> Server -> Verifier -> ThreeLegged -> Manager -> m (Response (Either ByteString (Token Permanent)))

-- | Request a <tt>Temporary</tt> <tt>Token</tt> based on the parameters of
--   a <a>ThreeLegged</a> protocol. This returns the raw response which
--   should be encoded as <tt>www-form-urlencoded</tt>.
--   
--   Throws <a>HttpException</a>s.
requestTemporaryTokenRaw :: (MonadIO m, MonadRandom m) => Cred Client -> Server -> ThreeLegged -> Manager -> m (Response ByteString)

-- | Request a 'Permanent <tt>Token</tt> based on the parameters of a
--   <a>ThreeLegged</a> protocol. This returns the raw response which
--   should be encoded as <tt>www-form-urlencoded</tt>.
--   
--   Throws <a>HttpException</a>s.
requestPermanentTokenRaw :: (MonadIO m, MonadRandom m) => Cred Temporary -> Server -> Verifier -> ThreeLegged -> Manager -> m (Response ByteString)

-- | Performs an interactive token request provided credentials,
--   configuration, and a way to convert a user authorization <a>URI</a>
--   into a <a>Verifier</a> out of band. Does not use any kind of TLS
--   protection---it will throw a <a>TlsNotSupported</a> exception if TLS
--   is required.
--   
--   Throws <a>HttpException</a>s.
requestTokenProtocol :: (MonadIO m, MonadRandom m) => Cred Client -> Server -> ThreeLegged -> (URI -> m Verifier) -> m (Maybe (Cred Permanent))

-- | Like <a>requestTokenProtocol</a> but allows for specification of the
--   <a>ManagerSettings</a>.
requestTokenProtocol' :: (MonadIO m, MonadRandom m) => ManagerSettings -> Cred Client -> Server -> ThreeLegged -> (URI -> m Verifier) -> m (Maybe (Cred Permanent))
instance GHC.Show.Show Network.OAuth.ThreeLegged.ThreeLegged


-- | Simplified Monadic interface for managing <tt>http-client</tt> and
--   <tt>oauthenticated</tt> state. Re-exposes all of the functionality
--   from <a>Network.OAuth</a> and <a>Network.OAuth.ThreeLegged</a>.
module Network.OAuth.Simple

-- | Sign a request using fresh credentials.
oauth :: MonadIO m => Request -> OAuthT ty m Request

-- | The simplest way to execute a set of authenticated requests. Produces
--   invalid <tt>ThreeLegged</tt> requests---use <a>runOAuth</a> to provide
--   <a>Server</a> and <a>ThreeLegged</a> configuration information.
runOAuthSimple :: OAuth ty a -> Cred ty -> IO a
runOAuth :: OAuth ty a -> Cred ty -> Server -> ThreeLegged -> IO a

-- | Run's an <a>OAuthT</a> using a fresh <a>EntropyPool</a>.
runOAuthT :: (MonadIO m) => OAuthT ty m a -> Cred ty -> Server -> ThreeLegged -> m a

-- | Perform authenticated requests using a shared <a>Manager</a> and a
--   particular set of <a>Cred</a>s.
newtype OAuthT ty m a
OAuthT :: ReaderT (OaConfig ty) m a -> OAuthT ty m a
[unOAuthT] :: OAuthT ty m a -> ReaderT (OaConfig ty) m a

-- | <a>OAuthT</a> wrapped over <a>IO</a>.
type OAuth ty = OAuthT ty IO
upgradeCred :: (ResourceToken ty', Monad m) => Token ty' -> OAuthT ty m (Cred ty')

-- | Given a <a>ResourceToken</a> of some kind, run an inner <a>OAuthT</a>
--   session with the same configuration but new credentials.
upgrade :: (ResourceToken ty', Monad m) => Token ty' -> OAuthT ty' m a -> OAuthT ty m a

-- | <a>Token</a>s are public, private key pairs and come in many
--   varieties, <a>Client</a>, <a>Temporary</a>, and <a>Permanent</a>.
data Token ty
Token :: {-# UNPACK #-} !Key -> {-# UNPACK #-} !Secret -> Token ty

-- | <a>Cred</a>entials pair a <a>Client</a> <a>Token</a> and either a
--   <a>Temporary</a> or <a>Permanent</a> token corresponding to a
--   particular set of user resources on the server.
data Cred ty

-- | <a>Client</a> <a>Cred</a>entials and <a>Token</a>s are assigned to a
--   particular client by the server and are used for all requests sent by
--   that client. They form the core component of resource specific
--   credentials.
data Client

-- | <a>Temporary</a> <a>Token</a>s and <a>Cred</a>entials are created
--   during authorization protocols and are rarely meant to be kept for
--   more than a few minutes. Typically they are authorized to access only
--   a very select set of server resources. During "three-legged
--   authorization" in OAuth 1.0 they are used to generate the
--   authorization request URI the client sends and, after that, in the
--   <a>Permanent</a> <a>Token</a> request.
data Temporary

-- | <a>Permanent</a> <a>Token</a>s and <a>Cred</a>entials are the primary
--   means of accessing server resources. They must be maintained by the
--   client for each user who authorizes that client to access resources on
--   their behalf.
data Permanent
clientCred :: Token Client -> Cred Client
temporaryCred :: Token Temporary -> Cred Client -> Cred Temporary
permanentCred :: Token Permanent -> Cred Client -> Cred Permanent

-- | Parses a <tt>www-form-urlencoded</tt> stream to produce a <a>Token</a>
--   if possible. The first result value is whether or not the token data
--   is OAuth 1.0a compatible.
--   
--   <pre>
--   &gt;&gt;&gt; fromUrlEncoded "oauth_token=key&amp;oauth_token_secret=secret"
--   Just (False, Token "key" "secret")
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fromUrlEncoded "oauth_token=key&amp;oauth_token_secret=secret&amp;oauth_callback_confirmed=true"
--   Just (True, Token "key" "secret")
--   </pre>
fromUrlEncoded :: ByteString -> Maybe (Bool, Token ty)

-- | The <a>Server</a> information contains details which parameterize how
--   a particular server wants to interpret OAuth requests.
data Server
Server :: ParameterMethod -> SignatureMethod -> Version -> Server
[parameterMethod] :: Server -> ParameterMethod
[signatureMethod] :: Server -> SignatureMethod
[oAuthVersion] :: Server -> Version

-- | The default <a>Server</a> parameterization uses OAuth recommended
--   parameters.
defaultServer :: Server

-- | The OAuth spec suggest that the OAuth parameter be passed via the
--   <tt>Authorization</tt> header, but allows for other methods of
--   transmission (see section "3.5. Parameter Transmission") so we select
--   the 'Server'\'s preferred method with this type.
data ParameterMethod

-- | Place the <a>Oa</a> parameters in the <tt>Authorization</tt> HTTP
--   header.
AuthorizationHeader :: ParameterMethod

-- | Augment the <tt>www-form-urlencoded</tt> request body with <a>Oa</a>
--   parameters.
RequestEntityBody :: ParameterMethod

-- | Augment the <tt>www-form-urlencoded</tt> query string with <a>Oa</a>
--   parameters.
QueryString :: ParameterMethod

-- | OAuth culminates in the creation of the <tt>oauth_signature</tt> which
--   signs and authenticates the request using the secret components of a
--   particular OAuth <a>Cred</a>.
--   
--   Several methods exist for generating these signatures, the most
--   popular being <a>HmacSha1</a>.
data SignatureMethod
HmacSha1 :: SignatureMethod
Plaintext :: SignatureMethod

-- | OAuth has progressed through several versions since its inception. In
--   particular, there are two community editions "OAuth Core 1.0" (2007)
--   and "OAuth Core 1.0a" (2009) along with the IETF Official version RFC
--   5849 (2010) which is confusingly named "OAuth 1.0".
--   
--   /Servers which only implement the obsoleted community edition "OAuth
--   Core 1.0" are susceptible to a session fixation attack./
--   
--   If at all possible, choose the RFC 5849 version (the <a>OAuth1</a>
--   value) as it is the modern standard. Some servers may only be
--   compliant with an earlier OAuth version---this should be tested
--   against each server, in particular the protocols defined in
--   <a>Network.OAuth.ThreeLegged</a>.
data Version

-- | OAuth Core 1.0 Community Edition
OAuthCommunity1 :: Version

-- | OAuth Core 1.0 Community Edition, Revision A
OAuthCommunity1a :: Version

-- | RFC 5849
OAuth1 :: Version

-- | Data parameterizing the "Three-legged OAuth" redirection-based
--   authorization protocol. These parameters cover the protocol as
--   described in the community editions <i>OAuth Core 1.0</i> and <i>OAuth
--   Core 1.0a</i> as well as RFC 5849.
data ThreeLegged
ThreeLegged :: Request -> Request -> Request -> Callback -> ThreeLegged

-- | Base <tt>Request</tt> for the "endpoint used by the client to obtain a
--   set of <tt>Temporary</tt> <tt>Cred</tt>entials" in the form of a
--   <tt>Temporary</tt> <tt>Token</tt>. This request is automatically
--   instantiated and performed during the first leg of the
--   <a>ThreeLegged</a> authorization protocol.
[temporaryTokenRequest] :: ThreeLegged -> Request

-- | Base <tt>Request</tt> for the "endpoint to which the resource owner is
--   redirected to grant authorization". This request must be performed by
--   the user granting token authorization to the client. Transmitting the
--   parameters of this request to the user is out of scope of
--   <tt>oauthenticated</tt>, but functions are provided to make it easier.
[resourceOwnerAuthorization] :: ThreeLegged -> Request

-- | Base <tt>Request</tt> for the "endpoint used by the client to request
--   a set of token credentials using the set of <tt>Temporary</tt>
--   <tt>Cred</tt>entials". This request is also instantiated and performed
--   by <tt>oauthenticated</tt> in order to produce a <tt>Permanent</tt>
--   <tt>Token</tt>.
[permanentTokenRequest] :: ThreeLegged -> Request

-- | The <tt>Callback</tt> parameter configures how the user is intended to
--   communicate the <tt>Verifier</tt> back to the client.
[callback] :: ThreeLegged -> Callback

-- | Convenience method for creating a <a>ThreeLegged</a> configuration
--   from a trio of URLs and a <tt>Callback</tt>. Returns <a>Nothing</a> if
--   one of the callback URLs could not be parsed correctly.
parseThreeLegged :: String -> String -> String -> Callback -> Maybe ThreeLegged

-- | When performing the second leg of the three-leg token request
--   workflow, the user must pass the <tt>oauth_verifier</tt> code back to
--   the client. In order to ensure that this protocol is secure, OAuth
--   demands that the client associates this "callback method" with the
--   temporary credentials generated for the workflow. This <a>Callback</a>
--   method may be a URL where the parameters are returned to or the string
--   <tt>"oob"</tt> which indicates that the user is responsible for
--   returning the <tt>oauth_verifier</tt> to the client <a>OutOfBand</a>.
data Callback
OutOfBand :: Callback
Callback :: Request -> Callback

-- | A <a>Verifier</a> is produced when a user authorizes a set of
--   <a>Temporary</a> <a>Cred</a>s. Using the <a>Verifier</a> allows the
--   client to request <a>Permanent</a> <a>Cred</a>s.
type Verifier = ByteString
requestTemporaryToken :: MonadIO m => Manager -> OAuthT Client m (Response (Either ByteString (Token Temporary)))
buildAuthorizationUrl :: Monad m => OAuthT Temporary m URI
requestPermanentToken :: MonadIO m => Manager -> Verifier -> OAuthT Temporary m (Response (Either ByteString (Token Permanent)))

-- | Run a full Three-legged authorization protocol using the simple
--   interface of this module. This is similar to the
--   <a>requestTokenProtocol</a> in <a>Network.OAuth.ThreeLegged</a>, but
--   offers better error handling due in part to the easier management of
--   configuration state.
requestTokenProtocol :: (Functor m, MonadIO m, MonadCatch m) => Manager -> (URI -> m Verifier) -> OAuthT Client m (Either TokenRequestFailure (Cred Permanent))
data TokenRequestFailure
OnTemporaryRequest :: HttpException -> TokenRequestFailure
BadTemporaryToken :: ByteString -> TokenRequestFailure
OnPermanentRequest :: HttpException -> TokenRequestFailure
BadPermanentToken :: ByteString -> TokenRequestFailure
instance GHC.Show.Show Network.OAuth.Simple.TokenRequestFailure
instance Control.Monad.IO.Class.MonadIO m => Control.Monad.IO.Class.MonadIO (Network.OAuth.Simple.OAuthT ty m)
instance Control.Monad.Catch.MonadThrow m => Control.Monad.Catch.MonadThrow (Network.OAuth.Simple.OAuthT ty m)
instance Control.Monad.Catch.MonadCatch m => Control.Monad.Catch.MonadCatch (Network.OAuth.Simple.OAuthT ty m)
instance GHC.Base.Monad m => Control.Monad.Reader.Class.MonadReader (Network.OAuth.Simple.OaConfig ty) (Network.OAuth.Simple.OAuthT ty m)
instance GHC.Base.Monad m => GHC.Base.Monad (Network.OAuth.Simple.OAuthT ty m)
instance GHC.Base.Applicative m => GHC.Base.Applicative (Network.OAuth.Simple.OAuthT ty m)
instance GHC.Base.Functor m => GHC.Base.Functor (Network.OAuth.Simple.OAuthT ty m)
instance Control.Monad.Trans.Class.MonadTrans (Network.OAuth.Simple.OAuthT ty)
