speakeasy

To allow users to scan the secret into an authenticator app, use the secret.otpauth_url with a QR code library (like the qrcode package) to generate a QR code image.

// Use the qrcode package
// npm install --save qrcode
var QRCode = require('qrcode');

// Get the data URL of the authenticator URL
QRCode.toDataURL(secret.otpauth_url, function(err, data_url) {
  console.log(data_url);

  // Display this data URL to the user in an <img> tag
  // Example:
  write('<img src="' + data_url + '">');
});

To use Speakeasy in your project, install it using npm:

npm install --save speakeasy

Verifies a counter-based token. You can use hotp.verify() for a simple boolean check or hotp.verifyDelta() to find the difference between the provided counter and the token's counter.

Windowing: Use the window parameter to allow for look-ahead (one-sided window). For example, if window is 10 and counter is 5, it checks tokens from 5 to 15.

Use speakeasy.generateSecret() to create a new secret key. This returns an object containing several encodings (ascii, hex, base32) and an otpauth_url used for QR code generation.

var secret = speakeasy.generateSecret();
// Returns an object with secret.ascii, secret.hex, and secret.base32.
// Also returns secret.otpauth_url, which we'll use later.

To display a secret via a QR code, generate an otpauth:// URL using speakeasy.otpauthURL(). This is especially important when using non-SHA1 algorithms.

Options:

• secret: The secret key.
• label: A label for the account (e.g., 'Name of Secret').
• algorithm: The hash algorithm (e.g., 'sha512').

// Generate a secret
var secret = speakeasy.generateSecret();

// Use otpauthURL() to get a custom authentication URL for SHA512
var url = speakeasy.otpauthURL({
  secret: secret.ascii, 
  label: 'Name of Secret', 
  algorithm: 'sha512'
});

// Pass URL into a QR code generator

Verify a TOTP token using speakeasy.totp.verify(). This returns true if the token is valid, otherwise false.

Options:

• secret: The secret key.
• encoding: The encoding of the secret.
• token: The token string to verify.
• window: The number of steps (time-steps) to check before and after the current time. A window of 2 with a 30 second step checks $\pm 60$ seconds.
• time: A custom timestamp in seconds to verify against.

// Verify a given token
var tokenValidates = speakeasy.totp.verify({
  secret: secret.base32,
  encoding: 'base32',
  token: '123456',
  window: 6
});
// Returns true if the token matches

Verifies a time-based token. You can use totp.verify() for a boolean check or totp.verifyDelta() to find the time-step difference.

Windowing: Unlike HOTP, totp.verifyDelta() uses a two-sided window. If window is 5 and counter is 1000, it checks tokens from 995 to 1005 inclusive.

Use speakeasy.totp.verifyDelta() to verify a TOTP token and determine how many time-steps it is away from the current time (or a specified time). This is useful for handling clock drift.

Returns:

• An object { delta: n } where n is the time-step difference.
• undefined if the token is not within the specified window.

Options:

• step: The time-step in seconds. Default is 30.
• window: The number of steps to check.

// Verify a given token is within 2 time-steps (+/- 2 minutes) from the server time-step.
var tokenDelta = speakeasy.totp.verifyDelta({
  secret: secret.base32,
  encoding: 'base32',
  token: '123456',
  window: 2,
  step: 60
});
// Returns {delta: 0} where the delta is the time step difference

Use speakeasy.generateSecret() to create a new secret key. You can specify a length in the options. The returned object provides the secret in different formats: secret.ascii, secret.hex, or secret.base32.

// Generate a secret key.
var secret = speakeasy.generateSecret({length: 20});
// Access using secret.ascii, secret.hex, or secret.base32.