tcell-hooks v1.1.0

By TCell.

TCell Hooks is to be used in conjuction with the tcell_agent to allow for custom event notifications of login failures and login successes.

Getting started

You can manually add it to your package.json file or install and save it with the following command:

npm install tcell-hooks --save

There are several options for calling the hooks from your application code:

• Providing an Express request object and having the TCell Agent extract the relevant details from it:

  var TCellHooks = require('tcell-hooks').v1;
  
  // successful login
  var username = 'some-user-id',
      sessionId = req.sessionID,
      password = 'some-password'
  TCellHooks.sendExpressLoginEventSuccess(req, username, sessionId, password);
  
  // failed login
  var username = 'some-user-id',
      sessionId = req.sessionID,
      userValid = false,
      password = 'some-password'
  TCellHooks.sendExpressLoginEventFailure(req, username, sessionId, userValid, password);

• Providing a Hapi request object and having the TCell Agent extract the relevant details from it:

  var TCellHooks = require('tcell-hooks').v1;
  
  // successful login
  var username = 'some-user-id',
      sessionId = 'session-id'
      password = 'some-password'
  TCellHooks.sendHapiLoginEventSuccess(req, username, sessionId, password);
  
  // failed login
  var username = 'some-user-id',
      sessionId = 'session-id'
      userValid = false,
      password = 'some-password'
  TCellHooks.sendHapiLoginEventFailure(req, username, sessionId, userValid, password);

• Providing each individual piece of information required for the TCell event:

  var TCellHooks = require('tcell-hooks').v1;
  
  // successful login
  // NOTE: this is how you would obtain this info from an ExpressJS request.
  //       Obtaining this info in a different framework will likely differ
  var username = 'some-user-id',
      sessionId = req.sessionID,
      userAgent = req.get('User-Agent'),
      referrer = req.get('Referrer'),
      remoteAddress = req.headers['x-forwarded-for'] || req.connection.remoteAddress,
      headerKeys = Object.keys(req.headers),
      documentUri = req.protocol + '://' + req.get('Host') + req.originalUrl,
      password = 'some-password'
  TCellHooks.sendLoginEventSuccess(
    username,
    sessionId,
    userAgent,
    referrer,
    remoteAddress,
    headerKeys,
    documentUri,
    password);
  
  // failed login
  // NOTE: this is how you would obtain this info from an ExpressJS request.
  //       Obtaining this info in a different framework will likely differ
  var username = 'some-user-id',
      sessionId = req.sessionID,
      userAgent = req.get('User-Agent'),
      referrer = req.get('Referrer'),
      remoteAddress = req.headers['x-forwarded-for'] || req.connection.remoteAddress,
      headerKeys = Object.keys(req.headers),
      documentUri = req.protocol + '://' + req.get('Host') + req.originalUrl,
      userValid = false,
      password = 'some-password'
  TCellHooks.sendLoginEventFailure(
    username,
    sessionId,
    userAgent,
    referrer,
    remoteAddress,
    headerKeys,
    documentUri,
    userValid,
    password);

   

Important Note

If the tcell_agent is not installed or if it's disabled, this code will do nothing and should have no performance effect on your app.  
 

API

function sendLoginEventSuccess (
  userId,
  sessionId,
  userAgent,
  referrer,
  remoteAddress,
  headerKeys,
  documentUri,
  password) {
}

String  userId - Identification used for the user (i.e. email, username)
String  sessionId - (Optional) Session ID for user logging in. This will be HMAC'ed by the Agent before being sent
String  userAgent - (Optional) User agent taken from header
String  referrer - (Optional) Referrer taken from header
String  remoteAddress - (Optional) IP of the Request
String  headerKeys - (Optional) An array of the header keys. The order is important (do not sort the array)
String  documentUri - (Optional) Document URI taken from request String  password - (Optional) Password for user logging in. This will be HMAC'ed by the Agent before being sent  

function sendLoginEventFailure (
  userId,
  sessionId,
  userAgent,
  referrer,
  remoteAddress,
  headerKeys,
  documentUri,
  userValid,
  password) {
}

String  userId - Identification used for the user (i.e. email, username)
String  sessionId - (Optional) Session ID for user logging in. This will be HMAC'ed by the Agent before being sent
String  userAgent - (Optional) User agent taken from header
String  referrer - (Optional) Referrer taken from header
String  remoteAddress - (Optional) IP of the Request
String  headerKeys - (Optional) An array of the header keys. The order is important (do not sort the array)
String  documentUri - (Optional) Document URI taken from request
Boolean userValid -  (Optional) Set as true if exists, other false. Defaults to null. String  password - (Optional) Password for user logging in. This will be HMAC'ed by the Agent before being sent  

function sendExpressLoginEventSuccess (
  request,
  userId,
  sessionId,
  password) {
}

Object  request - Request object provided by ExpressJS
String  userId - Identification used for the user (i.e. email, username)
String  sessionId - (Optional) Session ID for user logging in. This will be HMAC'ed by the Agent before being sent String  password - (Optional) Password for user logging in. This will be HMAC'ed by the Agent before being sent  

function sendExpressLoginEventFailure (
  request,
  userId,
  sessionId,
  userValid,
  password) {
}

Object  request - Request object provided by ExpressJS
String  userId - Identification used for the user (i.e. email, username)
String  sessionId - (Optional) Session ID for user logging in. This will be HMAC'ed by the Agent before being sent
Boolean userValid -  (Optional) Set as true if exists, other false. Defaults to null. String  password - (Optional) Password for user logging in. This will be HMAC'ed by the Agent before being sent  

function sendHapiLoginEventSuccess (
  request,
  userId,
  sessionId,
  password) {
}

Object  request - Request object provided by Hapi
String  userId - Identification used for the user (i.e. email, username)
String  sessionId - (Optional) Session ID for user logging in. This will be HMAC'ed by the Agent before being sent
String  password - (Optional) Password for user logging in. This will be HMAC'ed by the Agent before being sent  

function sendHapiLoginEventFailure (
  request,
  userId,
  sessionId,
  userValid,
  password) {
}

Object  request - Request object provided by Hapi
String  userId - Identification used for the user (i.e. email, username)
String  sessionId - (Optional) Session ID for user logging in. This will be HMAC'ed by the Agent before being sent
Boolean userValid -  (Optional) Set as true if exists, other false. Defaults to null. String  password - (Optional) Password for user logging in. This will be HMAC'ed by the Agent before being sent