❤
npm
Sign UpSign In

This package has been deprecated

Author message:

Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

passbyme2fa-client

1.1.2 • Public • Published

PassBy[ME] two factor authentication client

This library provides you with functionality to handle PassBy[ME] authentications.

For further information on PassBy[ME] please visit: www.passbyme.com and sign up for a free account. You can download our API documentation after login.

Table of contents

Installation

npm install passbyme2fa-client --save

Usage

To use the PassBy[ME] authentication SDK first you have to acquire the following:

  • Account authentication PFX and its password

You can get these after registering at www.passbyme.com, by hitting the "Sign up for free" button. To complete the registration you will need an Android or iOS device with the PassBy[ME] application installed.

If you login after registration you can download the PFX from the Application menu. You can add new applications to your registration by hitting the "New application". The application (along with its Application Id) will appear in the table below.

We suggest you to read the available User Guides and API documentation before you continue with the integration. You can download these from the Documentation section of the administartion website after login.

1. Require passbyme2fa-client in your code.

var pbm = require('passbyme2fa-client')({ /* params */	});

The params object consist of the following:

  • pfx: the authentication pfx. (See: https.request for details)
  • passphrase: the authentication pfx's passphrase. (See: https.request for details)
  • hostname: The address of the PassBy[ME] service to use. This parameter is optional. by default the SDK will connect to our public service. The PassBy[ME] service url is the following:
    • auth-sp.passbyme.com
  • message: The default message attached to each PassBy[ME] authentication request. Optional, de default value is 'Request for PassBy[ME] authentication'
  • You can supply any parameter accepted by http.request or https.request to influence the connection.

Throws MissingArgumentError when a required parameter is missing.

Example

var pbm = require('passbyme2fa-client')({
    pfx: fs.readFileSync('auth.pfx'), //required
    passphrase: 'password', //required
    hostname: 'auth-sp.passbyme.com', //optional, defaults to auth-sp.passbyme.com
    message : 'Request for PassBy[ME] authentication' //optional, defaults to 'Request for PassBy[ME] authentication'
});

2. Handling Messages

2.1 Sending messages

pbm.sendMessage(function(error, messageId){ /* code */ }, { /*params*/}, { /*httpParams*/}));

The callback function is called when the operation is finished. It should accept two paramters where first is an error parameter and the second is a sessionInfo data structure describing the session if there was no error.

Throws MissingArgumentError when a required parameter is missing. The error.propertyName and error.message properties both contain the name of the missing property. Throws BadArgumentError when a required parameter is malformed. The error.propertyName and error.message properties both contain information about the malformed property and the description of the problem.

The error object can be an instance of HttpError, or a PassByMEError.

The params object consists of the following:

  • recipients: A javascript array containing the PassBy[ME] ID-s of the recipients
  • subject: The subject of the message
  • body: 'The body of the message
  • availability: The availability of the message in seconds
  • type: One of pbm.MESSAGETYPE.AUTHORIZATION, pbm.MESSAGETYPE.MESSAGE or pbm.MESSAGETYPE.ESIGN. Use AUTHORIZATION to send authenticaion and authorization messages with arbitrary body. Use MESSAGE to send a general message with arbitrary body, or use ESIGN if the message body is containing an esign JSON You can supply any parameter accepted by http.request or https.request as the httpParams object to influence the connection.

Example

pbm.sendMessage(function(err,messageId){
    //handle error
    //process result
}, {
    recipients: ['pbmId1', 'pbmId2', 'pbmId3'],
    subject: 'test',
    body: 'body',
    availability: 23,
    type: pbm.MESSAGETYPE.MESSAGE
});

2.2 Tracking messages

pbm.trackMessage(function(error, messageId){ /* code */ }, { /*params*/, /*httpParams*/});

The callback function is called when the operation is finished. It should accept two paramters where first is an error parameter and the second is a sessionInfo data structure describing the session if there was no error.

Throws MissingArgumentError when a required parameter is missing. The error.propertyName and error.message properties both contain the name of the missing property.

The error object can be an instance of HttpError, or a PassByMEError.

The params object consists of the following:

  • messageId: The Id of the message to check You can supply any parameter accepted by http.request or https.request as the httpParams object to influence the connection.

Example

pbm.trackMessage(function(err,result){
    //handle error
    //process result
}, {
    messageId: myMessageId
});

2.3 Canceling messages

pbm.cancelMessage(function(error){ /* code */ }, { /*params*/});

The callback function is called when the operation is finished. It should accept a paramter, an error parameter. If the error is null, then the operation succeeded.

Throws MissingArgumentError when a required parameter is missing. The error.propertyName and error.message properties both contain the name of the missing property.

The error object can be an instance of HttpError, or a PassByMEError.

The params object consists of the following:

  • messageId: The Id of the session to cancel
  • You can supply any parameter accepted by http.request or https.request to influence the connection.

Example

pbm.cancelMessage(function(err){
    //handle error
}, {
    messageId: myMessageId
});

2.4 sessionInfo

The sessionInfoObject describes the state of a message session. It consits of the following fields:

  • messageId: The ID of the message that can be used to reference the message
  • expirationDate: The date and time until the message can be downloaded with the PassBy[ME] applications
  • recipients: An array of recipient objects. Each object consist of the following fields
    • userId: The PassBy[ME] ID of the user represented by this recipient object
    • status: The delivery status of this message for this user

Available statuses are:

  • PENDING: Initial status of the message.
  • NOTIFIED: The recipient has been notified about a new message.
  • DOWNLOADED: The recipient has downloaded the message, but has not uploaded the evidence yet.
  • SEEN: The recipient has seen the message and uploaded the evidence.
  • NOT_SEEN: The recipient has not seen the message.
  • NOT_NOTIFIED: The recipient has not received the notification.
  • NOT_DOWNLOADED: The recipient received the notification about the message but has not downloaded the message
  • NO_DEVICE: The message could not be sent because the recipient had no PassBy[ME] ready device that supports messaging.
  • FAILED: The message could not be sent because of an error.
  • DISABLED: The message could not be sent because the recipient is disabled.
  • CANCELLED: The message was cancelled by the sender.
  • APPROVED: Authentication has finished successfully.
  • DENIED: The user has cancelled the authentication.

Example

{
   "messageId" : " YzX95zUA1et2ijQ",
   "expirationDate" : "2015-06-11T13:06:12.658+02:00",
   "recipients" : [
       { "userId" : "pbmId1", "status" : "PENDING" },
       { "userId" : "pbmId2", "status" : "PENDING" },
       { "userId" : "pbmId3", "status" : "PENDING" }
   ]
}

Errors

BadArgumentError

Denotes that a required parameter is available, but contains malformed data.

Properties:

  • propertyName: The name of the property
  • message: description of the validation error

MissingArgumentError

Denotes that a required parameter is missing.

Properties:

  • propertyName: The name of the Missing property
  • message: Same as propertyName

HttpError

Denotes that the server responded with a HTTP error code. Has the same properties as http.IncomingMessage

PassByMEError

Denotes a PassBy[ME] specific error. See the API documentation for the possible error codes. Properties:

  • code: The code of the error
  • message: Optional message sent by the server

Release History

  • 1.0.0
    • Initial release
  • 1.0.1-3
    • Small typo fixes
  • 1.0.4
    • Improved documentation
    • Improved error handling
  • 1.0.5
    • Custom error objects for different error scenarios
  • 1.1.0
    • Messaging API support
  • 1.1.1
    • Removal of deprecated authentication API

Readme

Keywords

Package Sidebar

Install

npm i passbyme2fa-client

Weekly Downloads

2

Version

1.1.2

License

MIT

Last publish

Collaborators

  • pbmdev
Try on RunKit
Report malware