@CentralPing/passcode

A slightly opinionated stateless passcode manager.

Why slightly opinionated? Some people like more flexibility to implement solutions and this module hopefully allows for that. The few opinions employed in this module include the choice of hashing method, pbkdf2 (which can be configured), and a custom random 6 digit passcode generator (custom passcodes can also be provided). The biggest opinion however is to enforce signing the JWT and hashing the passcode. Doing niether results in an unsecure and effectively useless passcode verification as unsigned JWTs can be modified by anyone and unhashed codes can be read by anyone. If that is desired then this module is superflous as the underlying jsonwebtoken module can handle that directly.

Installation

npm i --save @centralping/passcode

API Reference

passcode~issue(security, [payload], claims, hash) ⇒ Object

Issues a signed token with a hashed passcode, token ID, expiration time and the stringified passcode.

Kind: inner method of passcode
Returns: Object - {error, value: {id, expires, passcode, token}}

Param	Type	Default	Description
security	Object
security.salt	String		A string to salt the passcode hash.
security.secret	String | Object		A string or key to sign the JWT.
[security.passcode]	String		The passcode (defaults to random 6 digit string).
[security.iss]	String		JWT issuer (used as additional verification).
[security.aud]	String		JWT audience (used as additional verification).
[security.sub]	String		JWT subject (used as additional verification).
[payload]	Object		Essentially a passthrough for jsonwebtoken payload support.
[payload.jti]	Date		JWT ID (defaults to a uuid.v4 value).
claims	Object		Essentially a passthrough for jsonwebtoken claims support.
[claims.expiresIn]	Number | String	5m	JWT expiration time span. In seconds or a parsable string for zeit/ms
hash	Object		Essentially a passthrough for pbkdf2 hashing options.
[hash.iterations]	Number	1000	Hash iterations.
[hash.keyLength]	Number	64	Hash length.
[hash.digest]	String	sha512	Hashing algorithm.
[hash.encoding]	String	hex	Hash encoding.

Example

const {error, value} = issue({salt, secret}, {email: '[e-mail]'});

passcode~verify(token, security, hash) ⇒ Object

Verifies a signed token with the provided challenge passcode.

Kind: inner method of passcode
Returns: Object - {error, value: {iat, jti, exp, ...TOKEN_PAYLOAD}}

Param	Type	Default	Description
token	String		The token to be verified
security	Object
security.passcode	String		The challenge passcode.
security.salt	String		A string to salt the challenge passcode hash.
security.secret	String | Object		A string or key to verify the JWT.
[security.iss]	String		JWT issuer (used as additional verification).
[security.aud]	String		JWT audience (used as additional verification).
[security.sub]	String		JWT subject (used as additional verification).
hash	Object		Essentially a passthrough for pbkdf2 hashing options.
[hash.iterations]	Number	1000	Hash iterations.
[hash.keyLength]	Number	64	Hash length.
[hash.digest]	String	sha512	Hashing algorithm.
[hash.encoding]	String	hex	Hash encoding.

Example

const {error, value} = verify(token, {passcode, salt, secret});

Examples

For Simple Verification With a Secret

const {issue, verify} = require('passcode');

// Generate a signed token with hashed random passcode
const {error, value: {id, expires, passcode, token}} = issue({
  salt: YOUR_SALT,
  secret: YOUR_SECRET
});
/**
 * Do something with the token
 */
// Verify token with code
const {error, value} = verify(token, {
  passcode: ENTERED_PASSCODE,
  salt: YOUR_SALT,
  secret: YOUR_SECRET
});

For Simple Verification With a Key

const {issue, verify} = require('passcode');
const secret = fs.readFileSync('public.pem');

// Generate a signed token with hashed random passcode
const {error, value: {id, expires, passcode, token}} = issue({
  salt: YOUR_SALT,
  secret
});
/**
 * Do something with the token
 */
// Verify token with code
const {error, value} = verify(token, {
  passcode: ENTERED_PASSCODE,
  salt: YOUR_SALT,
  secret
});

For Including Payload Data

const {issue, verify} = require('passcode');

// Generate a signed token with custom payload
const {error, value: {id, expires, passcode, token}} = issue({
  salt: YOUR_SALT,
  secret: YOUR_SECRET
}, {
  email: '[e-mail]'
});
/**
 * Do something with the token
 */
// Verify token with code
const {error, value: {email}} = verify(token, {
  passcode: ENTERED_PASSCODE,
  salt: YOUR_SALT,
  secret: YOUR_SECRET
});

License

MIT