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


-- | JSON Web Token (JWT) decoding and encoding
--   
--   JSON Web Token (JWT) is a compact URL-safe means of representing
--   claims to be transferred between two parties.
--   
--   To get started, see the documentation for the <a>Web.JWT</a> module.
@package jwt
@version 0.11.0


-- | This implementation of JWT is based on
--   <a>https://tools.ietf.org/html/rfc7519</a> but currently only
--   implements the minimum required to work with the Atlassian Connect
--   framework and GitHub App
--   
--   Known limitations:
--   
--   <ul>
--   <li>Only HMAC SHA-256 and RSA SHA-256 algorithms are currently a
--   supported signature algorithm</li>
--   <li>There is currently no verification of time related information
--   (<a>exp</a>, <a>nbf</a>, <a>iat</a>).</li>
--   <li>Registered claims are not validated</li>
--   </ul>
module Web.JWT

-- | Decode a claims set without verifying the signature. This is useful if
--   information from the claim set is required in order to verify the
--   claim (e.g. the secret needs to be retrieved based on unverified
--   information from the claims set).
--   
--   <pre>
--   &gt;&gt;&gt; :{
--    let
--        input = Data.Text.pack "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzb21lIjoicGF5bG9hZCJ9.Joh1R2dYzkRvDkqv3sygm5YyK8Gi4ShZqbhK2gxcs2U"
--        mJwt = decode input
--    in fmap header mJwt
--   :}
--   Just (JOSEHeader {typ = Just "JWT", cty = Nothing, alg = Just HS256, kid = Nothing})
--   </pre>
--   
--   and
--   
--   <pre>
--   &gt;&gt;&gt; :{
--    let
--        input = T.pack "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzb21lIjoicGF5bG9hZCJ9.Joh1R2dYzkRvDkqv3sygm5YyK8Gi4ShZqbhK2gxcs2U"
--        mJwt = decode input
--    in fmap claims mJwt
--   :}
--   Just (JWTClaimsSet {iss = Nothing, sub = Nothing, aud = Nothing, exp = Nothing, nbf = Nothing, iat = Nothing, jti = Nothing, unregisteredClaims = ClaimsMap {unClaimsMap = fromList [("some",String "payload")]}})
--   </pre>
decode :: Text -> Maybe (JWT UnverifiedJWT)

-- | Using a known secret and a decoded claims set verify that the
--   signature is correct and return a verified JWT token as a result.
--   
--   This will return a VerifiedJWT if and only if the signature can be
--   verified using the given secret.
--   
--   The separation between decode and verify is very useful if you are
--   communicating with multiple different services with different secrets
--   and it allows you to lookup the correct secret for the unverified JWT
--   before trying to verify it. If this is not an isuse for you (there
--   will only ever be one secret) then you should just use
--   <a>decodeAndVerifySignature</a>.
--   
--   <pre>
--   &gt;&gt;&gt; :{
--    let
--        input = T.pack "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzb21lIjoicGF5bG9hZCJ9.Joh1R2dYzkRvDkqv3sygm5YyK8Gi4ShZqbhK2gxcs2U"
--        mUnverifiedJwt = decode input
--        mVerifiedJwt = verify (toVerify . hmacSecret . T.pack $ "secret") =&lt;&lt; mUnverifiedJwt
--    in signature =&lt;&lt; mVerifiedJwt
--   :}
--   Just (Signature "Joh1R2dYzkRvDkqv3sygm5YyK8Gi4ShZqbhK2gxcs2U")
--   </pre>
verify :: VerifySigner -> JWT UnverifiedJWT -> Maybe (JWT VerifiedJWT)

-- | Decode a claims set and verify that the signature matches by using the
--   supplied secret. The algorithm is based on the supplied header value.
--   
--   This will return a VerifiedJWT if and only if the signature can be
--   verified using the given secret.
--   
--   <pre>
--   &gt;&gt;&gt; :{
--    let
--        input = T.pack "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzb21lIjoicGF5bG9hZCJ9.Joh1R2dYzkRvDkqv3sygm5YyK8Gi4ShZqbhK2gxcs2U"
--        mJwt = decodeAndVerifySignature (toVerify . hmacSecret . T.pack $ "secret") input
--    in signature =&lt;&lt; mJwt
--   :}
--   Just (Signature "Joh1R2dYzkRvDkqv3sygm5YyK8Gi4ShZqbhK2gxcs2U")
--   </pre>
decodeAndVerifySignature :: VerifySigner -> Text -> Maybe (JWT VerifiedJWT)

-- | Encode a claims set using the given secret
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   let
--       cs = mempty { -- mempty returns a default JWTClaimsSet
--          iss = stringOrURI . T.pack $ "Foo"
--        , unregisteredClaims = ClaimsMap $ Map.fromList [(T.pack "http://example.com/is_root", (Bool True))]
--       }
--       key = hmacSecret . T.pack $ "secret-key"
--   in encodeSigned key mempty cs
--   :}
--   "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJodHRwOi8vZXhhbXBsZS5jb20vaXNfcm9vdCI6dHJ1ZSwiaXNzIjoiRm9vIn0.vHQHuG3ujbnBUmEp-fSUtYxk27rLiP2hrNhxpyWhb2E"
--   </pre>
encodeSigned :: EncodeSigner -> JOSEHeader -> JWTClaimsSet -> Text

-- | Encode a claims set without signing it
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   let cs = mempty
--             { iss = stringOrURI . Data.Text.pack $ "Foo"
--             , iat = numericDate 1394700934
--             , unregisteredClaims = ClaimsMap $ Data.Map.fromList [(Data.Text.pack "http://example.com/is_root", (Bool True))]
--             }
--   in encodeUnsigned cs mempty
--   :}
--   "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjEzOTQ3MDA5MzQsImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlLCJpc3MiOiJGb28ifQ."
--   </pre>
encodeUnsigned :: JWTClaimsSet -> JOSEHeader -> Text

-- | Try to extract the value for the issue claim field <a>iss</a> from the
--   web token in JSON form
tokenIssuer :: Text -> Maybe StringOrURI

-- | Create a Secret using the given key. Consider using
--   <tt>HMACSecret</tt> instead if your key is not already a
--   <a>Data.Text</a>.
hmacSecret :: Text -> EncodeSigner

-- | Create an RSA <a>PrivateKey</a> from PEM contents
--   
--   <pre>
--   readRsaSecret &lt;$&gt; BS.readFile "foo.pem"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :{
--     -- A random example key created with `ssh-keygen -t rsa`
--     fromJust . readRsaSecret . C8.pack $ unlines
--         [ "-----BEGIN RSA PRIVATE KEY-----"
--         , "MIIEowIBAAKCAQEAkkmgbLluo5HommstpHr1h53uWfuN3CwYYYR6I6a2MzAHIMIv"
--         , "8Ak2ha+N2UDeYsfVhZ/DOnE+PMm2RpYSaiYT0l2a7ZkmRSbcyvVFt3XLePJbmUgo"
--         , "ieyccS4uYHeqRggdWH9His3JaR2N71N9iU0+mY5nu2+15iYw3naT/PSx01IzBqHN"
--         , "Zie1z3FYX09FgOs31mcR8VWj8DefxbKE08AW+vDMT2AmUC2b+Gqk6SqRz29HuPBs"
--         , "yyV4Xl9CgzcCWjuXTv6mevDygo5RVZg34U6L1iFRgwwHbrLcd2N97wlKz+OiDSgM"
--         , "sbZWA0i2D9ZsDR9rdEdXzUIw6toIRYZfeI9QYQIDAQABAoIBAEXkh5Fqx0G/ZLLi"
--         , "olwDo2u4OTkkxxJ6vutYsEJ4VHUAbWdpYB3/SN12kv9JzvbDI3FEc7JoiKPifAQd"
--         , "j47HwpCvyGXc1jwT5UnTBgwxa5XNtZX2s+ex9Mzek6njgqcTGXI+3Z+j0qc2R6og"
--         , "6cm/7jjPoSAcr3vWo2KmpO4muw+LbYoSGo0Jydoa5cGtkmDfsjjrMw7mDoRttdhw"
--         , "WdhS+q2aJPFI7q7itoYUd7KLe3nOeM0zd35Pc8Qc6jGk+JZxQdXrb/NrSNgAATcN"
--         , "GGS226Q444N0pAfc188IDcAtQPSJpzbs/1+TPzE4ov/lpHTr91hXr3RLyVgYBI01"
--         , "jrggfAECgYEAwaC4iDSZQ+8eUx/zR973Lu9mvQxC2BZn6QcOtBcIRBdGRlXfhwuD"
--         , "UgwVZ2M3atH5ZXFuQ7pRtJtj7KCFy7HUFAJC15RCfLjx+n39bISNp5NOJEdI+UM+"
--         , "G2xMHv5ywkULV7Jxb+tSgsYIvJ0tBjACkif8ahNjgVJmgMSOgdHR2pkCgYEAwWkN"
--         , "uquRqKekx4gx1gJYV7Y6tPWcsZpEcgSS7AGNJ4UuGZGGHdStpUoJICn2cFUngYNz"
--         , "eJXOg+VhQJMqQx9c+u85mg/tJluGaw95tBAafspwvhKewlO9OhQeVInPbXMUwrJ0"
--         , "PS3XV7c74nxm6Nn4QHlM07orn3lOiWxZF8BBSQkCgYATjwSU3ZtNvW22v9d3PxKA"
--         , "7zXVitOFuF2usEPP9TOkjSVQHYSCw6r0MrxGwULry2IB2T9mH//42mlxkZVySfg+"
--         , "PSw7UoKUzqnCv89Fku4sKzkNeRXp99ziMEJQLyuwbAEFTsUepQqkoxRm2QmfQmJA"
--         , "GUHqBSNcANLR1wj+HA+yoQKBgQCBlqj7RQ+AaGsQwiFaGhIlGtU1AEgv+4QWvRfQ"
--         , "B64TJ7neqdGp1SFP2U5J/bPASl4A+hl5Vy6a0ysZQEGV3cLH41e98SPdin+C5kiO"
--         , "LCgEghGOWR2EaOUlr+sui3OvCueDGFynzTo27G+0bdPp+nnKgTvHtTqbTIUhsLX1"
--         , "IvzbOQKBgH4q36jgBb9T3hjXtWyrytlmFtBdw0i+UiMvMlnOqujGhcnOk5UMyxOQ"
--         , "sQI+/31jIGbmlE7YaYykR1FH3LzAjO4J1+m7vv5fIRdG8+sI01xTc8UAdbmWtK+5"
--         , "TK1oLP43BHH5gRAfIlXj2qmap5lEG6If/xYB4MOs8Bui5iKaJlM5"
--         , "-----END RSA PRIVATE KEY-----"
--         ]
--   :}
--   PrivateKey {private_pub = PublicKey {public_size = 256, public_n = 1846..., public_e = 65537}, private_d = 8823..., private_p = 135..., private_q = 1358..., private_dP = 1373..., private_dQ = 9100..., private_qinv = 8859...}
--   </pre>
readRsaSecret :: ByteString -> Maybe PrivateKey

-- | Create an RSA <a>PublicKey</a> from PEM contents
--   
--   <pre>
--    readRsaPublicKey &lt;$&gt; BS.readFile "foo.pub"
--   &gt;&gt; :{
--   </pre>
--   
--   fromJust . readRsaPublicKey . Data.ByteString.Char8.pack $
--   Data.List.unlines [ "-----BEGIN PUBLIC KEY-----" ,
--   <a>MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA12d4M6f3QQ9E52fVjoJ7</a>
--   , "HorKvi1A83f4YL4e7TU0Lj/73+afrRBtnAdl8dIrnYHLWRdL9T4+yw7+AimQgj1R" ,
--   "zZO5FQN<i>qVxygkPeMKAZ53nObi2NyBbQYmRrBjx7rOz7UddI5qo</i>ApTWNrSBjDKK"
--   , "1splbuO2BoTrsHlsSoJDWps/5SwpEF4GGkn5c4nZRnpnayUZqolp+HwDK2Dys9MO" ,
--   "GEIsUil1+k<i>76T96pBnPf6mf3X0IacTCNjJcztSaHCPWre1q45miQUGVlTmhfg</i>6"
--   , "L8xmNRxz4BZdv8Nv6STfRTsn6PqiaabD0vITVsF1AapdHohmPMwe+lG5ebUJEh8p" ,
--   <a>HQIDAQAB</a> , "-----END PUBLIC KEY-----" ] :} PublicKey
--   {public_size = 256, public_n =
--   27192258298637073499814714121384917708820189127612408586659742012541332375187297990620494295383503839337630959589643433993051132285579261506578281787130221431792495554016841577295914249477128682873612830754668313951998800261326356221445367133271958375798088350587817966390021082924122322621635687775325677158394714044356852489350530339926527334843762933075425870780010358838296108179073735084189560997222261973170469403371017667139302904425235800700389626242339763391588052694912470921008842459564204534000688115202764921141372629345213727775126077560633656612484128950350759146471467728292335666402631045889956718877,
--   public_e = 65537}
readRsaPublicKey :: ByteString -> Maybe PublicKey

-- | Converts an EncodeSigner into a VerifySigner If you can encode then
--   you can always verify; but the reverse is not always true.
toVerify :: EncodeSigner -> VerifySigner

-- | Extract the claims set from a JSON Web Token
claims :: JWT r -> JWTClaimsSet

-- | Extract the header from a JSON Web Token
header :: JWT r -> JOSEHeader

-- | Extract the signature from a verified JSON Web Token
signature :: JWT r -> Maybe Signature

-- | Convert the <a>aud</a> claim in a <a>JWTClaimsSet</a> into a
--   `[StringOrURI]`
auds :: JWTClaimsSet -> [StringOrURI]

-- | Convert the <a>NominalDiffTime</a> into an IntDate. Returns a Nothing
--   if the argument is invalid (e.g. the NominalDiffTime must be
--   convertible into a positive Integer representing the seconds since
--   epoch).

-- | <i>Deprecated: Use numericDate instead. intDate will be removed in
--   1.0</i>
intDate :: NominalDiffTime -> Maybe IntDate

-- | Convert the <a>NominalDiffTime</a> into an NumericDate. Returns a
--   Nothing if the argument is invalid (e.g. the NominalDiffTime must be
--   convertible into a positive Integer representing the seconds since
--   epoch).
numericDate :: NominalDiffTime -> Maybe NumericDate

-- | Convert a <a>Text</a> into a <a>StringOrURI</a>. Returns a Nothing if
--   the String cannot be converted (e.g. if the String contains a
--   <tt>:</tt> but is *not* a valid URI).
stringOrURI :: Text -> Maybe StringOrURI

-- | Convert a <a>StringOrURI</a> into a <a>Text</a>. Returns the T.Text
--   representing the String as-is or a Text representation of the URI
--   otherwise.
stringOrURIToText :: StringOrURI -> Text

-- | Return the seconds since 1970-01-01T0:0:0Z UTC for the given
--   <a>IntDate</a>
secondsSinceEpoch :: NumericDate -> NominalDiffTime

-- | JSON Web Token without signature verification
data UnverifiedJWT

-- | JSON Web Token that has been successfully verified
data VerifiedJWT
data Signature
data VerifySigner
VerifyHMACSecret :: ByteString -> VerifySigner
VerifyRSAPrivateKey :: PrivateKey -> VerifySigner
VerifyRSAPublicKey :: PublicKey -> VerifySigner
data EncodeSigner
EncodeHMACSecret :: ByteString -> EncodeSigner
EncodeRSAPrivateKey :: PrivateKey -> EncodeSigner

-- | The JSON Web Token
data JWT r
data Algorithm

-- | HMAC using SHA-256 hash algorithm
HS256 :: Algorithm

-- | RSA using SHA-256 hash algorithm
RS256 :: Algorithm

-- | The JWT Claims Set represents a JSON object whose members are the
--   claims conveyed by the JWT.
data JWTClaimsSet
JWTClaimsSet :: Maybe StringOrURI -> Maybe StringOrURI -> Maybe (Either StringOrURI [StringOrURI]) -> Maybe IntDate -> Maybe IntDate -> Maybe IntDate -> Maybe StringOrURI -> ClaimsMap -> JWTClaimsSet

-- | The iss (issuer) claim identifies the principal that issued the JWT.
[iss] :: JWTClaimsSet -> Maybe StringOrURI

-- | The sub (subject) claim identifies the principal that is the subject
--   of the JWT.
[sub] :: JWTClaimsSet -> Maybe StringOrURI

-- | The aud (audience) claim identifies the audiences that the JWT is
--   intended for according to draft 18 of the JWT spec, the aud claim is
--   option and may be present in singular or as a list.
[aud] :: JWTClaimsSet -> Maybe (Either StringOrURI [StringOrURI])

-- | The exp (expiration time) claim identifies the expiration time on or
--   after which the JWT MUST NOT be accepted for processing. Its value
--   MUST be a number containing an IntDate value.
[exp] :: JWTClaimsSet -> Maybe IntDate

-- | The nbf (not before) claim identifies the time before which the JWT
--   MUST NOT be accepted for processing.
[nbf] :: JWTClaimsSet -> Maybe IntDate

-- | The iat (issued at) claim identifies the time at which the JWT was
--   issued.
[iat] :: JWTClaimsSet -> Maybe IntDate

-- | The jti (JWT ID) claim provides a unique identifier for the JWT.
[jti] :: JWTClaimsSet -> Maybe StringOrURI
[unregisteredClaims] :: JWTClaimsSet -> ClaimsMap
newtype ClaimsMap
ClaimsMap :: Map Text Value -> ClaimsMap
[unClaimsMap] :: ClaimsMap -> Map Text Value

-- | A JSON numeric value representing the number of seconds from
--   1970-01-01T0:0:0Z UTC until the specified UTC date/time.

-- | <i>Deprecated: Use NumericDate instead. IntDate will be removed in
--   1.0</i>
type IntDate = NumericDate

-- | A JSON numeric value representing the number of seconds from
--   1970-01-01T0:0:0Z UTC until the specified UTC date/time.
data NumericDate

-- | A JSON string value, with the additional requirement that while
--   arbitrary string values MAY be used, any value containing a ":"
--   character MUST be a URI [RFC3986]. StringOrURI values are compared as
--   case-sensitive strings with no transformations or canonicalizations
--   applied.
data StringOrURI

-- | <i>Deprecated: Use JOSEHeader instead. JWTHeader will be removed in
--   1.0</i>
type JWTHeader = JOSEHeader

-- | JOSE Header, describes the cryptographic operations applied to the JWT
data JOSEHeader
JOSEHeader :: Maybe Text -> Maybe Text -> Maybe Algorithm -> Maybe Text -> JOSEHeader

-- | The typ (type) Header Parameter defined by [JWS] and [JWE] is used to
--   declare the MIME Media Type [IANA.MediaTypes] of this complete JWT in
--   contexts where this is useful to the application. This parameter has
--   no effect upon the JWT processing.
[typ] :: JOSEHeader -> Maybe Text

-- | The cty (content type) Header Parameter defined by [JWS] and [JWE] is
--   used by this specification to convey structural information about the
--   JWT.
[cty] :: JOSEHeader -> Maybe Text

-- | The alg (algorithm) used for signing the JWT. The HS256 (HMAC using
--   SHA-256) is the only required algorithm in addition to "none" which
--   means that no signature will be used.
--   
--   See
--   <a>http://tools.ietf.org/html/draft-ietf-jose-json-web-algorithms-23#page-6</a>
[alg] :: JOSEHeader -> Maybe Algorithm

-- | The "kid" (key ID) Header Parameter is a hint indicating which key was
--   used to secure the JWS. This parameter allows originators to
--   explicitly signal a change of key to recipients. The structure of the
--   "kid" value is unspecified. Its value MUST be a case-sensitive string.
--   Use of this Header Parameter is OPTIONAL.
--   
--   See <a>https://tools.ietf.org/html/rfc7515#section-4.1.4</a>
[kid] :: JOSEHeader -> Maybe Text

-- | Create an RSAPrivateKey from PEM contents
--   
--   Please, consider using <a>readRsaSecret</a> instead.
rsaKeySecret :: String -> IO (Maybe EncodeSigner)
instance GHC.Show.Show Web.JWT.Signature
instance GHC.Classes.Ord Web.JWT.NumericDate
instance GHC.Classes.Eq Web.JWT.NumericDate
instance GHC.Show.Show Web.JWT.NumericDate
instance GHC.Classes.Eq Web.JWT.StringOrURI
instance GHC.Show.Show Web.JWT.Algorithm
instance GHC.Classes.Eq Web.JWT.Algorithm
instance GHC.Show.Show Web.JWT.JOSEHeader
instance GHC.Classes.Eq Web.JWT.JOSEHeader
instance GHC.Show.Show Web.JWT.ClaimsMap
instance GHC.Classes.Eq Web.JWT.ClaimsMap
instance GHC.Classes.Eq Web.JWT.JWTClaimsSet
instance GHC.Show.Show Web.JWT.JWTClaimsSet
instance GHC.Show.Show (Web.JWT.JWT r)
instance GHC.Base.Monoid Web.JWT.JWTClaimsSet
instance GHC.Base.Semigroup Web.JWT.JWTClaimsSet
instance Data.Aeson.Types.ToJSON.ToJSON Web.JWT.JWTClaimsSet
instance Data.Aeson.Types.FromJSON.FromJSON Web.JWT.JWTClaimsSet
instance GHC.Base.Monoid Web.JWT.ClaimsMap
instance GHC.Base.Semigroup Web.JWT.ClaimsMap
instance GHC.Base.Monoid Web.JWT.JOSEHeader
instance GHC.Base.Semigroup Web.JWT.JOSEHeader
instance Data.Aeson.Types.FromJSON.FromJSON Web.JWT.JOSEHeader
instance Data.Aeson.Types.ToJSON.ToJSON Web.JWT.JOSEHeader
instance Data.Aeson.Types.ToJSON.ToJSON Web.JWT.Algorithm
instance Data.Aeson.Types.FromJSON.FromJSON Web.JWT.Algorithm
instance GHC.Show.Show Web.JWT.StringOrURI
instance Data.Aeson.Types.ToJSON.ToJSON Web.JWT.StringOrURI
instance Data.Aeson.Types.FromJSON.FromJSON Web.JWT.StringOrURI
instance Data.Aeson.Types.ToJSON.ToJSON Web.JWT.NumericDate
instance Data.Aeson.Types.FromJSON.FromJSON Web.JWT.NumericDate
instance GHC.Classes.Eq Web.JWT.Signature