# gatekey

Authentication library for gatekey.io

## Install

```
$ npm i @immutabl3/gatekey
```

## Usage

### Basics

Instantiating **gatekey** takes an options configuration object and returns a promise

```js
import gatekey from '@immutabl3/gatekey';

gatekey({
  // prevent redirecting so that we can see the error in catch
  redirect: false
})
  .then(results => {
    // results = {token: '', redirect: fn, payload: {}}
  })
  .catch(error => {
    // the error that occurred when authenticating
  });
```

### Options

You can pass these options at instantiation.

```js
gatekey(
  // options
  {
    redirect: false
  }
);
```

- **key** _string_ [`gatekey`]: what key to store validation value under
- **secure** _boolean_ [`true`]: if the page is required to be loaded over 'https'
- **redirect** _boolean_ [`true`]: if the page should be redirected on failure
- **alwaysValidate** _boolean_ [`false`]: whether the page should always be validated on load. Default behavior is to randomly retry if the page has already been authenticated
- **expiration** _number_ [`43200000`]: ms after page when validation is no longer valid. After this duration, the page will be validated on next load. Defaults to 12 hours.
- **retryChance** _number_ [`0.1`]: the percent chance that a validated page load will revalidate. This is to prevent alterations to the store giving permenant access.
- **store** _object_ [`sessionStore`]: the store used to the validation value. This object can be replaced as long as it implements two methods: `getItem` and `setItem` with behavior following sessionStore.
- **fallbackToMemoryStore** _boolean_ [`true`]: if the store is unavailble, should gatekey fallback to an in-memory store. Local and session storage may be unavailable in incognito modes.

### Results

After instantiation, gatekey provides an object.

```js
gatekey()
  .then(results => {
    // results = {token: '', redirect: fn, payload: {}}
  });
```

- **token** _string_: the [JWT](https://jwt.io/) used to authorize access 
- **redirect** _function_: a redirect function that will redirect the page to the custom error page. Takes an optional error as a parameter.
- **payload** _object_: the deserialized JSON payload from the JWT

## Support

Uses [`fetch`](https://caniuse.com/#feat=fetch) and [`Object.assign`](http://kangax.github.io/compat-table/es6/#test-Object_static_methods_Object.assign). If older browser (or IE 11) support is required, polyfills are available:

- [`fetch`](https://github.com/github/fetch) 
- [`Object.assign`](https://www.npmjs.com/package/object.assign)