Neutrino Packing Machine

    @centralping/passcode

    0.1.1 • Public • Published

    @CentralPing/passcode

    Build Status Coverage Status Dependency Status Greenkeeper Status Known Vulnerabilities

    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: 'foo@bar.com'});

    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: 'foo@bar.com'
    });
    /**
     * 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

    Install

    npm i @centralping/passcode

    DownloadsWeekly Downloads

    0

    Version

    0.1.1

    License

    MIT

    Unpacked Size

    38.5 kB

    Total Files

    11

    Last publish

    Collaborators

    • centralping-admin
    • jasoncust