@ladjs/passport-otp-strategy/README.md

TOTP authentication strategy for Passport.

# @ladjs/passport-otp-strategy

[![npm](https://img.shields.io/npm/v/@ladjs/passport-otp-strategy.svg)](https://www.npmjs.com/package/@ladjs/passport-otp-strategy)
[![Build Status](https://secure.travis-ci.org/ladjs/passport-otp-strategy.png)](http://travis-ci.org/ladjs/passport-otp-strategy)


## Table of Contents

* [Foreword](#foreword)
* [Install](#install)
* [Usage](#usage)
* [Examples](#examples)
* [Tests](#tests)
* [Contributors](#contributors)
* [License](#license)


## Foreword

This is a fork of [passport-otp](https://github.com/ejhayes/passport-otp), which is a fork itself of the [Passport-TOTP](https://github.com/jaredhanson/passport-totp) library and uses `otplib` instead of `notp`.

[Passport](http://passportjs.org/) strategy for two-factor authentication using
a [TOTP](http://tools.ietf.org/html/rfc6238) value.

This module lets you authenticate using a TOTP value in your Node.js
applications.  By plugging into Passport, TOTP two-factor authentication can be
easily and unobtrusively integrated into any application or framework that
supports [Connect](http://www.senchalabs.org/connect/)-style middleware,
including [Express](http://expressjs.com/).  TOTP values can be generated by
hardware devices or software applications, including [Google Authenticator](https://code.google.com/p/google-authenticator/)
and [Authy](https://authy.com/).

Note that in contrast to most Passport strategies, TOTP authentication requires
that a user already be authenticated using an initial factor.  Requirements
regarding when to require a second factor are a matter of application-level
policy, and outside the scope of both Passport and this strategy.


## Install

```sh
npm install @ladjs/passport-otp-strategy
```


## Usage

#### Configure Strategy

The TOTP authentication strategy authenticates a user using a TOTP value
generated by a hardware device or software application (known as a token).  The
strategy requires a `setup` callback.

The `setup` callback accepts a previously authenticated `user` and calls `done`
providing a `key` used to verify the token value.  Authentication
fails if the value is not verified.

```js
passport.use(new OtpStrategy(
  {
    codeField: 'code',
    authenticator: {}
  }
  function(user, done) {
    TotpKey.findOne({ userId: user.id }, function (err, key) {
      if (err) { return done(err); }
      return done(null, key.key);
    });
  }
));
```

You can find a full listing of `authenticator` options [here](https://www.npmjs.com/package/otplib#available-options). Note that the `crypto` library will be used by default. If you want to change that, you can specify it in `authenticator.crypto` (more on that [here](https://www.npmjs.com/package/otplib#using-specific-otp-implementations)).

#### Authenticate Requests

Use `passport.authenticate()`, specifying the `'otp'` strategy, to authenticate
requests.

For example, as route middleware in an [Express](http://expressjs.com/)
application:

```js
app.post(
  '/verify-otp',
  passport.authenticate('otp', { failureRedirect: '/verify-otp' }),
  function(req, res) {
    req.session.authFactors = [ 'otp' ];
    res.redirect('/');
  }
);
```


## Examples

For a complete, working example, refer [Lad](https://lad.js.org) source code.


## Tests

```sh
npm install
npm run test
```


## Contributors

| Name             | Website                          |
| ---------------- | -------------------------------- |
| **Eric Hayes**   | <https://github.com/ejhayes>     |
| **Jared Hanson** | <https://github.com/jaredhanson> |


## License

[MIT](LICENSE) © [Eric Hayes](https://github.com/ejhayes)