# foodog

A simple and easy to use JWT library. This is a convenient wrapper around [jose](https://github.com/potatosalad/erlang-jose).

I made this library so I wouldn't have to write the same JWT module for every app I make. foodog includes sensible defaults and the ability to override them. The default field names are based on the JWT standard.

Generated tokens include these fields by default:
- jti (random number of up to 9 digits)
- exp (1 hour expiration time)
- iss (domain name issuer)
- sub_jwk (key id used for signature)

Verifying tokens will by default:
- Use the sub_jwk field to determine the correct key for signature verification
- Check if token is expired
- Check if domain key is correct

## Build

    rebar3 compile

## Test

    rebar3 eunit
    rebar3 ct

## Usage

Set these config variables:

    {foodog, [{issuer, <<"example.com">>},
              {keys, [{<<"kid1">>, <<"1234567">>}]}]}.

The keys field is a proplist to make key rotations seamless. foodog will by default use the first key in the propslist
to generate the token. When verifying it will lookup in the proplist for the key used to sign the token.

To seamlessly rotate a key, add your new key to the top of the proplist. After a given amount of time that all sessions using the old key are closed, simply remove the old key from the proplist.

Then generate and verify JWT's like this:

    {ok, Token} = foodog:generate(#{<<"foobar">> => <<"barfoo">>}),
    {ok, Payload} = foodog:verify(Token)

### Override Defaults 

You can override the defaults by passing in an options map.

    Options = #{exp => {hours, 2},
                iss => <<"example2.com">>},

    {ok, Token} = foodog:generate(#{<<"foo">> => <<"bar">>}, Options),
    {ok, Payload} = foodog:verify(Token, Options).

### Expiration Time

The default expiration time for a token is 1 hour.

This can be adjusted by passing in arg to generate like this:

    {ok, Token} = foodog:generate(Payload, {hours, 2}).

This will make a token that is good for 2 hours. 

foodog supports these expiration time intervals:

- seconds
- minutes (60 seconds)
- hours (60 minutes)
- days (24 hours)
- weeks (7 days)
- months (4 weeks)
- years (365 days)

## License

Apache V2