-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Simple OAuth for http-client -- -- Warning: 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. -- -- oauthenticated is a Haskell library implementing OAuth -- protocols atop the minimalistic http-client HTTP client -- library extracted from http-conduit. Network.OAuth -- offers simple functions for signing -- Network.HTTP.Client.Requests along with tools for -- Network.OAuth.Credential management and -- Network.OAuth.Server configuration. Network.OAuth.Simple -- 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 Network.OAuth 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 -- Network.OAuth.Types.Params.Version for more details. -- -- Currently oauthenticated 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.3.0.0 -- | Credentials, Creds, are built from Tokens, -- public/private key pairs, and come in 3 varieties. -- -- module Network.OAuth.Types.Credentials -- | Tokens are public, private key pairs and come in many -- varieties, Client, Temporary, and Permanent. data Token ty Token :: {-# UNPACK #-} !Key -> {-# UNPACK #-} !Secret -> Token ty -- | Token Keys are public keys which allow a server to -- uniquely identify a particular Token. type Key = ByteString -- | Token Secrets are private keys which the Token -- uses for cryptographic purposes. type Secret = ByteString -- | Client Credentials and Tokens 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 -- | Temporary Tokens and Credentials 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 -- Permanent Token request. data Temporary -- | Permanent Tokens and Credentials 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 www-form-urlencoded stream to produce a Token -- if possible. The first result value is whether or not the token data -- is OAuth 1.0a compatible. -- -- 
--   >>> fromUrlEncoded "oauth_token=key&oauth_token_secret=secret"
--   Just (False, Token "key" "secret")
--
-- -- 
--   >>> fromUrlEncoded "oauth_token=key&oauth_token_secret=secret&oauth_callback_confirmed=true"
--   Just (True, Token "key" "secret")
--
fromUrlEncoded :: ByteString -> Maybe (Bool, Token ty) -- | Credentials pair a Client Token and either a -- Temporary or Permanent 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 Token. key :: Functor f => (Key -> f Key) -> Token ty -> f (Token ty) -- | Lens on the key secret component of a Token. secret :: Functor f => (Secret -> f Secret) -> Token ty -> f (Token ty) -- | A lens on the client Token in any Cred. clientToken :: Functor f => (Token Client -> f (Token Client)) -> Cred ty -> f (Cred ty) -- | A lens focused on the resource Token when available. The only -- instances of ResourceToken are Temporary and -- Permanent. This can be used to upgrade Temporary -- Creds to Permanent Creds. 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 -- Token that is by default completely blank. In this way we can -- talk about the resource Token of even Client -- Creds. -- -- 
--   >>> getResourceTokenDef (clientCred $ Token "key" "secret")
--   Token "" ""
--
getResourceTokenDef :: Cred ty -> Token ty -- | Produce a signingKey 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. -- -- 
--   \secret -> signingKey (clientCred $ Token "key" secret) == (pctEncode secret <> "&" <> "")
--
signingKey :: Cred ty -> ByteString instance Data.Data.Data Network.OAuth.Types.Credentials.Client instance Data.Data.Data Network.OAuth.Types.Credentials.Temporary instance Data.Data.Data Network.OAuth.Types.Credentials.Permanent 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 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 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) -- | OAuth Parameters -- -- OAuth 1.0 operates by creating a set of "oauth parameters" here called -- Oa which augment a request with OAuth specific metadata. They -- may be used to augment the request by one of several -- ParameterMethods. module Network.OAuth.Types.Params -- | The OAuth spec suggest that the OAuth parameter be passed via the -- Authorization 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 Oa parameters in the Authorization HTTP -- header. AuthorizationHeader :: ParameterMethod -- | Augment the www-form-urlencoded request body with Oa -- parameters. RequestEntityBody :: ParameterMethod -- | Augment the www-form-urlencoded query string with Oa -- parameters. QueryString :: ParameterMethod -- | OAuth culminates in the creation of the oauth_signature which -- signs and authenticates the request using the secret components of a -- particular OAuth Cred. -- -- Several methods exist for generating these signatures, the most -- popular being HmacSha1. 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 OAuth1 -- 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 -- Network.OAuth.ThreeLegged. data Version -- | OAuth Core 1.0 Community Edition OAuthCommunity1 :: Version -- | OAuth Core 1.0 Community Edition, Revision A OAuthCommunity1a :: Version -- | RFC 5849 OAuth1 :: Version -- | When performing the second leg of the three-leg token request -- workflow, the user must pass the oauth_verifier 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 Callback -- method may be a URL where the parameters are returned to or the string -- "oob" which indicates that the user is responsible for -- returning the oauth_verifier to the client OutOfBand. data Callback OutOfBand :: Callback Callback :: Request -> Callback -- | An Epoch time format timestamp. newtype Timestamp Timestamp :: UTCTime -> Timestamp -- | Create a Timestamp deterministically from a POSIX Epoch Time. timestampFromSeconds :: Integer -> Timestamp -- | The Server 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 Server parameterization uses OAuth recommended -- parameters. defaultServer :: Server -- | A Verifier is produced when a user authorizes a set of -- Temporary Creds. Using the Verifier allows the -- client to request Permanent Creds. type Verifier = ByteString -- | Some special OAuth requests use extra oauth_* parameters. For -- example, when requesting a temporary credential, it's necessary that a -- oauth_callback parameter be specified. -- WorkflowParams allows these extra parameters to be specified. data Workflow -- | No special OAuth parameters needed Standard :: Workflow TemporaryTokenRequest :: Callback -> Workflow -- | Includes the oauth_verifier PermanentTokenRequest :: ByteString -> Workflow -- | The OaPin 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 OaPin is referentially -- transparent and thus has none of the necessary security features---it -- should never be used in an actual transaction! emptyPin :: OaPin -- | Creates a new, unique, unpredictable OaPin. This should be used -- quickly as dependent on the OAuth server settings it may expire. freshPin :: (MonadRandom m, MonadIO m) => m OaPin -- | Uses emptyPin to create an empty set of params Oa. emptyOa :: Cred ty -> Oa ty -- | Uses freshPin to create a fresh, default set of params -- Oa. freshOa :: (MonadRandom m, MonadIO m) => Cred ty -> m (Oa ty) -- | The Oa 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 -- Server 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 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 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.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.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.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 GHC.Show.Show Network.OAuth.Types.Params.Workflow 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.Oa ty) 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 Request about -- to be sent, Server parameters, and a full Oa we append a -- set of parameters to the Request 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 Request is specified by -- ParameterMethod with one built from the apropriate OAuth -- parameters (passed as a Query). -- -- Currently this actually replaces the Authorization -- header if one exists. This may be a bad idea if the realm -- parameter is pre-set, perhaps. -- -- TODO: Parse Authorization header and augment it. -- -- Currently this actually replaces 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 Request 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 not a set of OAuth -- parameters--- dropping this assumption would prevent this from being -- pure. bodyParams :: Request -> Query queryParams :: Request -> Query -- | OAuth tools for using http-client for authenticated requests. -- -- The functions here form the simplest basis for sending OAuthenticated -- Requests. In order to generate credentials according to the -- OAuth "three-legged workflow" use actions in the -- Network.OAuth.ThreeLegged module. module Network.OAuth -- | Sign a request with a fresh set of parameters. Uses MonadRandom -- IO, getting new entropy for each signing and thus is potentially -- dangerous if used too frequently. In almost all cases, -- oauth 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 emptyPin to create an empty set of params Oa. emptyOa :: Cred ty -> Oa ty -- | Uses freshPin to create a fresh, default set of params -- Oa. freshOa :: (MonadRandom m, MonadIO m) => Cred ty -> m (Oa ty) -- | An "empty" pin useful for testing. This OaPin is referentially -- transparent and thus has none of the necessary security features---it -- should never be used in an actual transaction! emptyPin :: OaPin -- | Creates a new, unique, unpredictable OaPin. This should be used -- quickly as dependent on the OAuth server settings it may expire. freshPin :: (MonadRandom m, MonadIO m) => m OaPin -- | Tokens are public, private key pairs and come in many -- varieties, Client, Temporary, and Permanent. data Token ty Token :: {-# UNPACK #-} !Key -> {-# UNPACK #-} !Secret -> Token ty -- | Credentials pair a Client Token and either a -- Temporary or Permanent token corresponding to a -- particular set of user resources on the server. data Cred ty -- | Client Credentials and Tokens 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 -- | Temporary Tokens and Credentials 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 -- Permanent Token request. data Temporary -- | Permanent Tokens and Credentials 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 www-form-urlencoded stream to produce a Token -- if possible. The first result value is whether or not the token data -- is OAuth 1.0a compatible. -- -- 
--   >>> fromUrlEncoded "oauth_token=key&oauth_token_secret=secret"
--   Just (False, Token "key" "secret")
--
-- -- 
--   >>> fromUrlEncoded "oauth_token=key&oauth_token_secret=secret&oauth_callback_confirmed=true"
--   Just (True, Token "key" "secret")
--
fromUrlEncoded :: ByteString -> Maybe (Bool, Token ty) -- | The Server 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 Server parameterization uses OAuth recommended -- parameters. defaultServer :: Server -- | The OAuth spec suggest that the OAuth parameter be passed via the -- Authorization 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 Oa parameters in the Authorization HTTP -- header. AuthorizationHeader :: ParameterMethod -- | Augment the www-form-urlencoded request body with Oa -- parameters. RequestEntityBody :: ParameterMethod -- | Augment the www-form-urlencoded query string with Oa -- parameters. QueryString :: ParameterMethod -- | OAuth culminates in the creation of the oauth_signature which -- signs and authenticates the request using the secret components of a -- particular OAuth Cred. -- -- Several methods exist for generating these signatures, the most -- popular being HmacSha1. 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 OAuth1 -- 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 -- Network.OAuth.ThreeLegged. 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 -- Redirection-Based Authorization. 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 OAuth Core 1.0 and OAuth -- Core 1.0a as well as RFC 5849. data ThreeLegged ThreeLegged :: Request -> Request -> Request -> Callback -> ThreeLegged -- | Base Request for the "endpoint used by the client to obtain a -- set of Temporary Credentials" in the form of a -- Temporary Token. This request is automatically -- instantiated and performed during the first leg of the -- ThreeLegged authorization protocol. [temporaryTokenRequest] :: ThreeLegged -> Request -- | Base Request 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 -- oauthenticated, but functions are provided to make it easier. [resourceOwnerAuthorization] :: ThreeLegged -> Request -- | Base Request for the "endpoint used by the client to request -- a set of token credentials using the set of Temporary -- Credentials". This request is also instantiated and performed -- by oauthenticated in order to produce a Permanent -- Token. [permanentTokenRequest] :: ThreeLegged -> Request -- | The Callback parameter configures how the user is intended to -- communicate the Verifier back to the client. [callback] :: ThreeLegged -> Callback -- | Convenience method for creating a ThreeLegged configuration -- from a trio of URLs and a Callback. Returns Nothing 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 oauth_verifier 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 Callback -- method may be a URL where the parameters are returned to or the string -- "oob" which indicates that the user is responsible for -- returning the oauth_verifier to the client OutOfBand. data Callback OutOfBand :: Callback Callback :: Request -> Callback -- | A Verifier is produced when a user authorizes a set of -- Temporary Creds. Using the Verifier allows the -- client to request Permanent Creds. type Verifier = ByteString -- | Returns the raw result if the Response could not be parsed as a -- valid Token. Importantly, in RFC 5849 compliant modes this -- requires that the token response includes -- callback_confirmed=true. See also -- requestTemporaryTokenRaw. -- -- Throws HttpExceptions. requestTemporaryToken :: (MonadIO m, MonadRandom m) => Cred Client -> Server -> ThreeLegged -> Manager -> m (Response (Either ByteString (Token Temporary))) -- | Produce a URI which the user should be directed to in order to -- authorize a set of Temporary Creds. buildAuthorizationUrl :: Cred Temporary -> ThreeLegged -> URI -- | Returns Nothing if the response could not be decoded as a -- Token. See also requestPermanentTokenRaw. -- -- Throws HttpExceptions. requestPermanentToken :: (MonadIO m, MonadRandom m) => Cred Temporary -> Server -> Verifier -> ThreeLegged -> Manager -> m (Response (Either ByteString (Token Permanent))) -- | Request a Temporary Token based on the parameters of -- a ThreeLegged protocol. This returns the raw response which -- should be encoded as www-form-urlencoded. -- -- Throws HttpExceptions. requestTemporaryTokenRaw :: (MonadIO m, MonadRandom m) => Cred Client -> Server -> ThreeLegged -> Manager -> m (Response ByteString) -- | Request a 'Permanent Token based on the parameters of a -- ThreeLegged protocol. This returns the raw response which -- should be encoded as www-form-urlencoded. -- -- Throws HttpExceptions. 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 URI -- into a Verifier out of band. Does not use any kind of TLS -- protection---it will throw a TlsNotSupported exception if TLS -- is required. -- -- Throws HttpExceptions. requestTokenProtocol :: (MonadIO m, MonadRandom m) => Cred Client -> Server -> ThreeLegged -> (URI -> m Verifier) -> m (Maybe (Cred Permanent)) -- | Like requestTokenProtocol but allows for specification of the -- ManagerSettings. 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 http-client and -- oauthenticated state. Re-exposes all of the functionality -- from Network.OAuth and Network.OAuth.ThreeLegged. 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 ThreeLegged requests---use runOAuth to provide -- Server and ThreeLegged configuration information. runOAuthSimple :: OAuth ty a -> Cred ty -> IO a runOAuth :: OAuth ty a -> Cred ty -> Server -> ThreeLegged -> IO a -- | Run's an OAuthT using a fresh EntropyPool. runOAuthT :: MonadIO m => OAuthT ty m a -> Cred ty -> Server -> ThreeLegged -> m a -- | Perform authenticated requests using a shared Manager and a -- particular set of Creds. 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 -- | OAuthT wrapped over IO. type OAuth ty = OAuthT ty IO upgradeCred :: (ResourceToken ty', Monad m) => Token ty' -> OAuthT ty m (Cred ty') -- | Given a ResourceToken of some kind, run an inner OAuthT -- session with the same configuration but new credentials. upgrade :: (ResourceToken ty', Monad m) => Token ty' -> OAuthT ty' m a -> OAuthT ty m a -- | Tokens are public, private key pairs and come in many -- varieties, Client, Temporary, and Permanent. data Token ty Token :: {-# UNPACK #-} !Key -> {-# UNPACK #-} !Secret -> Token ty -- | Credentials pair a Client Token and either a -- Temporary or Permanent token corresponding to a -- particular set of user resources on the server. data Cred ty -- | Client Credentials and Tokens 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 -- | Temporary Tokens and Credentials 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 -- Permanent Token request. data Temporary -- | Permanent Tokens and Credentials 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 www-form-urlencoded stream to produce a Token -- if possible. The first result value is whether or not the token data -- is OAuth 1.0a compatible. -- -- 
--   >>> fromUrlEncoded "oauth_token=key&oauth_token_secret=secret"
--   Just (False, Token "key" "secret")
--
-- -- 
--   >>> fromUrlEncoded "oauth_token=key&oauth_token_secret=secret&oauth_callback_confirmed=true"
--   Just (True, Token "key" "secret")
--
fromUrlEncoded :: ByteString -> Maybe (Bool, Token ty) -- | The Server 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 Server parameterization uses OAuth recommended -- parameters. defaultServer :: Server -- | The OAuth spec suggest that the OAuth parameter be passed via the -- Authorization 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 Oa parameters in the Authorization HTTP -- header. AuthorizationHeader :: ParameterMethod -- | Augment the www-form-urlencoded request body with Oa -- parameters. RequestEntityBody :: ParameterMethod -- | Augment the www-form-urlencoded query string with Oa -- parameters. QueryString :: ParameterMethod -- | OAuth culminates in the creation of the oauth_signature which -- signs and authenticates the request using the secret components of a -- particular OAuth Cred. -- -- Several methods exist for generating these signatures, the most -- popular being HmacSha1. 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 OAuth1 -- 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 -- Network.OAuth.ThreeLegged. 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 OAuth Core 1.0 and OAuth -- Core 1.0a as well as RFC 5849. data ThreeLegged ThreeLegged :: Request -> Request -> Request -> Callback -> ThreeLegged -- | Base Request for the "endpoint used by the client to obtain a -- set of Temporary Credentials" in the form of a -- Temporary Token. This request is automatically -- instantiated and performed during the first leg of the -- ThreeLegged authorization protocol. [temporaryTokenRequest] :: ThreeLegged -> Request -- | Base Request 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 -- oauthenticated, but functions are provided to make it easier. [resourceOwnerAuthorization] :: ThreeLegged -> Request -- | Base Request for the "endpoint used by the client to request -- a set of token credentials using the set of Temporary -- Credentials". This request is also instantiated and performed -- by oauthenticated in order to produce a Permanent -- Token. [permanentTokenRequest] :: ThreeLegged -> Request -- | The Callback parameter configures how the user is intended to -- communicate the Verifier back to the client. [callback] :: ThreeLegged -> Callback -- | Convenience method for creating a ThreeLegged configuration -- from a trio of URLs and a Callback. Returns Nothing 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 oauth_verifier 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 Callback -- method may be a URL where the parameters are returned to or the string -- "oob" which indicates that the user is responsible for -- returning the oauth_verifier to the client OutOfBand. data Callback OutOfBand :: Callback Callback :: Request -> Callback -- | A Verifier is produced when a user authorizes a set of -- Temporary Creds. Using the Verifier allows the -- client to request Permanent Creds. 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 -- requestTokenProtocol in Network.OAuth.ThreeLegged, 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 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 GHC.Show.Show Network.OAuth.Simple.TokenRequestFailure instance Control.Monad.Trans.Class.MonadTrans (Network.OAuth.Simple.OAuthT ty)