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


-- | Microsoft Authentication API
--   
--   Bindings to the Microsoft Identity API / Active Directory (AD) for
--   building applications that use either Delegated or App-only
--   permissions. Helper functions are provided for building OAuth2
--   authentication flows and keep tokens transactionally secure and up to
--   date.
@package ms-auth
@version 0.2.0.0


-- | Decode and validate a JWT token
--   
--   provides <a>Validation</a> function for the individual fields as well
module Network.OAuth2.JWT

-- | Decode a string into a <a>JWTClaimsSet</a>
jwtClaims :: Text -> Maybe JWTClaimsSet

-- | <pre>
--   sub
--   </pre>
decValidSub :: JWTClaimsSet -> Validation (NonEmpty JWTException) UserSub

-- | <pre>
--   exp
--   </pre>
decValidExp :: Maybe NominalDiffTime -> UTCTime -> JWTClaimsSet -> Validation (NonEmpty JWTException) UTCTime

-- | <pre>
--   nbf
--   </pre>
decValidNbf :: UTCTime -> JWTClaimsSet -> Validation (NonEmpty JWTException) UTCTime

-- | <pre>
--   email
--   </pre>
decValidEmail :: JWTClaimsSet -> Validation (NonEmpty JWTException) UserEmail

-- | <pre>
--   aud
--   </pre>
decValidAud :: ApiAudience -> JWTClaimsSet -> Validation (NonEmpty JWTException) Text

-- | <tt>sub</tt> field
data UserSub
userSub :: UserSub -> Text
data UserEmail
userEmail :: UserEmail -> Text

-- | intended audience of the token (== API key ID )
data ApiAudience
apiAudience :: ApiAudience -> Text

-- | Possible exception states of authentication request
data JWTException
JEMalformedJWT :: Text -> JWTException
JEClaimNotFound :: String -> JWTException
JEAudienceNotFound :: ApiAudience -> JWTException
JEExpiredToken :: UTCTime -> JWTException
JENotYetValid :: UTCTime -> JWTException
JENoToken :: JWTException
instance Data.Aeson.Types.FromJSON.FromJSONKey Network.OAuth2.JWT.UserSub
instance Data.Aeson.Types.ToJSON.ToJSONKey Network.OAuth2.JWT.UserSub
instance Data.Aeson.Types.FromJSON.FromJSON Network.OAuth2.JWT.UserSub
instance Data.Aeson.Types.ToJSON.ToJSON Network.OAuth2.JWT.UserSub
instance GHC.Show.Show Network.OAuth2.JWT.UserSub
instance Data.String.IsString Network.OAuth2.JWT.UserSub
instance GHC.Generics.Generic Network.OAuth2.JWT.UserSub
instance GHC.Classes.Ord Network.OAuth2.JWT.UserSub
instance GHC.Classes.Eq Network.OAuth2.JWT.UserSub
instance Data.Aeson.Types.FromJSON.FromJSONKey Network.OAuth2.JWT.UserEmail
instance Data.Aeson.Types.ToJSON.ToJSONKey Network.OAuth2.JWT.UserEmail
instance Data.Aeson.Types.FromJSON.FromJSON Network.OAuth2.JWT.UserEmail
instance Data.Aeson.Types.ToJSON.ToJSON Network.OAuth2.JWT.UserEmail
instance GHC.Show.Show Network.OAuth2.JWT.UserEmail
instance Data.String.IsString Network.OAuth2.JWT.UserEmail
instance GHC.Generics.Generic Network.OAuth2.JWT.UserEmail
instance GHC.Classes.Ord Network.OAuth2.JWT.UserEmail
instance GHC.Classes.Eq Network.OAuth2.JWT.UserEmail
instance Data.String.IsString Network.OAuth2.JWT.ApiAudience
instance GHC.Generics.Generic Network.OAuth2.JWT.ApiAudience
instance GHC.Show.Show Network.OAuth2.JWT.ApiAudience
instance GHC.Classes.Ord Network.OAuth2.JWT.ApiAudience
instance GHC.Classes.Eq Network.OAuth2.JWT.ApiAudience
instance GHC.Show.Show Network.OAuth2.JWT.JWTClaims
instance GHC.Classes.Eq Network.OAuth2.JWT.JWTClaims
instance GHC.Generics.Generic Network.OAuth2.JWT.JWTException
instance GHC.Classes.Ord Network.OAuth2.JWT.JWTException
instance GHC.Classes.Eq Network.OAuth2.JWT.JWTException
instance GHC.Show.Show Network.OAuth2.JWT.JWTException
instance GHC.Exception.Type.Exception Network.OAuth2.JWT.JWTException
instance Data.Aeson.Types.ToJSON.ToJSON Network.OAuth2.JWT.JWTException
instance Data.Aeson.Types.ToJSON.ToJSON Network.OAuth2.JWT.ApiAudience


-- | Settings for using Azure Active Directory as OAuth identity provider
--   
--   Both <tt>Delegated</tt> (On-Behalf-Of) and <tt>App-only</tt> (i.e.
--   Client Credentials) authentication flows are supported. The former is
--   useful when a user needs to login and delegate some permissions to the
--   application (i.e. accessing personal data), whereas the second is for
--   server processes and automation accounts.
module Network.OAuth2.Provider.AzureAD
data AzureAD

-- | Azure OAuth application (i.e. with user consent screen)
--   
--   NB : scope <tt>offline_access</tt> is ALWAYS requested
--   
--   create app at <a>https://go.microsoft.com/fwlink/?linkid=2083908</a>
--   
--   also be aware to find the right client id. see
--   <a>https://stackoverflow.com/a/70670961</a>
azureADApp :: Text -> ClientId -> ClientSecret -> [Scope] -> IdpApplication 'ClientCredentials AzureAD

-- | Configuration object of the OAuth2 application
data OAuthCfg
OAuthCfg :: Text -> ClientId -> ClientSecret -> [Scope] -> AuthorizeState -> URI -> OAuthCfg

-- | application name
[$sel:oacAppName:OAuthCfg] :: OAuthCfg -> Text

-- | app client ID : see <a>https://stackoverflow.com/a/70670961</a>
[$sel:oacClientId:OAuthCfg] :: OAuthCfg -> ClientId

-- | app client secret "
[$sel:oacClientSecret:OAuthCfg] :: OAuthCfg -> ClientSecret

-- | OAuth2 and OIDC scopes
[$sel:oacScopes:OAuthCfg] :: OAuthCfg -> [Scope]

-- | OAuth2 <tt>state</tt> (a random string,
--   <a>https://www.rfc-editor.org/rfc/rfc6749#section-10.12</a> )
[$sel:oacAuthState:OAuthCfg] :: OAuthCfg -> AuthorizeState

-- | OAuth2 redirect URI
[$sel:oacRedirectURI:OAuthCfg] :: OAuthCfg -> URI

-- | 
--   <a>https://learn.microsoft.com/en-us/azure/active-directory/develop/userinfo</a>
data AzureADUser

-- | Azure OAuth application (i.e. with user consent screen)
--   
--   NB : scopes <tt>openid</tt> and <tt>offline_access</tt> are ALWAYS
--   requested since the library assumes we have access to refresh tokens
--   and ID tokens
--   
--   Reference on Microsoft Graph permissions :
--   <a>https://learn.microsoft.com/en-us/graph/permissions-reference</a>
--   
--   create app at <a>https://go.microsoft.com/fwlink/?linkid=2083908</a>
--   
--   also be aware to find the right client id. see
--   <a>https://stackoverflow.com/a/70670961</a>
azureOAuthADApp :: OAuthCfg -> IdpApplication 'AuthorizationCode AzureAD
instance GHC.Show.Show Network.OAuth2.Provider.AzureAD.AzureAD
instance GHC.Classes.Eq Network.OAuth2.Provider.AzureAD.AzureAD
instance GHC.Show.Show Network.OAuth2.Provider.AzureAD.AzureADUser
instance GHC.Classes.Ord Network.OAuth2.Provider.AzureAD.AzureADUser
instance GHC.Classes.Eq Network.OAuth2.Provider.AzureAD.AzureADUser
instance Data.Aeson.Types.FromJSON.FromJSON Network.OAuth2.Provider.AzureAD.AzureADUser


-- | MS Identity user session based on OAuth tokens
--   
--   The library supports the following authentication scenarios :
--   
--   <ul>
--   <li><a>Client Credentials</a> (server/server or automation
--   accounts)</li>
--   <li><a>Authorization Code</a> (with human users being prompted to
--   delegate some access rights to the app)</li>
--   </ul>
--   
--   and provides functions to keep tokens up to date in the background.
module Network.OAuth2.Session

-- | App has (at most) one token at a time
type Token t = TVar (Maybe t)
newNoToken :: MonadIO m => m (Token t)
expireToken :: MonadIO m => Token t -> m ()
readToken :: MonadIO m => Token t -> m (Maybe t)

-- | Fetch an OAuth token and keep it updated. Should be called as a first
--   thing in the app
--   
--   NB : forks a thread in the background
--   
--   
--   <a>https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-client-creds-grant-flow</a>
fetchUpdateToken :: MonadIO m => IdpApplication 'ClientCredentials AzureAD -> Token OAuth2Token -> Manager -> m ()

-- | Login endpoint
--   
--   see <a>azureADApp</a>
loginEndpoint :: MonadIO m => IdpApplication 'AuthorizationCode AzureAD -> RoutePattern -> Scotty m ()

-- | The identity provider redirects the client to the <tt>reply</tt>
--   endpoint as part of the OAuth flow :
--   <a>https://learn.microsoft.com/en-us/graph/auth-v2-user?view=graph-rest-1.0&amp;tabs=http#authorization-response</a>
--   
--   NB : forks a thread per logged in user to keep their tokens up to date
replyEndpoint :: MonadIO m => IdpApplication 'AuthorizationCode AzureAD -> Tokens UserSub OAuth2Token -> Manager -> RoutePattern -> Scotty m ()

-- | transactional token store
type Tokens uid t = TVar (TokensData uid t)

-- | Create an empty <a>Tokens</a> object
newTokens :: (MonadIO m, Ord uid) => m (Tokens uid t)

-- | <tt>sub</tt> field
data UserSub

-- | Look up a user identifier and return their current token, if any
lookupUser :: (MonadIO m, Ord uid) => Tokens uid t -> uid -> m (Maybe t)

-- | Remove a user, i.e. they will have to authenticate once more
expireUser :: (MonadIO m, Ord uid) => Tokens uid t -> uid -> m ()

-- | return a list representation of the <a>Tokens</a> object
tokensToList :: MonadIO m => Tokens k a -> m [(k, a)]

-- | Decode the App Service ID token header
--   <tt>X-MS-TOKEN-AAD-ID-TOKEN</tt>, look its user up in the local token
--   store, supply token <tt>t</tt> to continuation. If the user
--   <tt>sub</tt> cannot be found in the token store the browser is
--   redirected to the login URI.
--   
--   Special case of <a>aadHeaderIdToken</a>
withAADUser :: MonadIO m => Tokens UserSub t -> Text -> (t -> Action m ()) -> Action m ()
type Scotty = ScottyT Text
type Action = ActionT Text
instance GHC.Classes.Eq Network.OAuth2.Session.OAuthSessionError
instance (GHC.Show.Show uid, GHC.Show.Show t) => GHC.Show.Show (Network.OAuth2.Session.TokensData uid t)
instance (GHC.Classes.Eq uid, GHC.Classes.Eq t) => GHC.Classes.Eq (Network.OAuth2.Session.TokensData uid t)
instance GHC.Exception.Type.Exception Network.OAuth2.Session.OAuthSessionError
instance GHC.Show.Show Network.OAuth2.Session.OAuthSessionError