Node

Getting started

You can manually add it to your package.json or install and save it with the following command: npm install tcell-hooks --save

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

  1. By providing an Express request object and having the tCell Agent extract the relevant details from it:

    1
    var TCellHooks = require('tcell-hooks').v1;
    2
    3
    // successful login
    4
    var username = 'some-user-id',
    5
    sessionId = req.sessionID
    6
    TCellHooks.sendExpressLoginEventSuccess(username, sessionId, req);
    7
    8
    // failed login
    9
    var username = 'some-user-id',
    10
    sessionId = req.sessionID,
    11
    userValid = false
    12
    TCellHooks.sendExpressLoginEventFailure(username, sessionId, req, userValid);
  2. By providing a Hapi request object and having the TCell Agent extract the relevant details from it:

    1
    var TCellHooks = require('tcell-hooks').v1;
    2
    3
    // successful login
    4
    var username = 'some-user-id',
    5
    sessionId = 'session-id'
    6
    TCellHooks.sendHapiLoginEventSuccess(req, username, sessionId);
    7
    8
    // failed login
    9
    var username = 'some-user-id',
    10
    sessionId = 'session-id'
    11
    userValid = false
    12
    TCellHooks.sendHapiLoginEventFailure(req, username, sessionId, userValid);
  3. By providing each individual piece of information required for the tCell event:

    1
    var TCellHooks = require('tcell-hooks').v1;
    2
    3
    // successful login
    4
    // NOTE: this is how you would obtain this info from an ExpressJS request.
    5
    // Obtaining this info in a different framework will likely differ
    6
    var username = 'some-user-id',
    7
    sessionId = req.sessionID,
    8
    userAgent = req.get('User-Agent'),
    9
    referrer = req.get('Referrer'),
    10
    remoteAddress = req.headers['x-forwarded-for'] || req.connection.remoteAddress,
    11
    headerKeys = Object.keys(req.headers),
    12
    documentUri = req.protocol + '://' + req.get('Host') + req.originalUrl
    13
    TCellHooks.sendLoginEventSuccess(
    14
    username,
    15
    sessionId,
    16
    userAgent,
    17
    referrer,
    18
    remoteAddress,
    19
    headerKeys,
    20
    documentUri);
    21
    22
    // failed login
    23
    // NOTE: this is how you would obtain this info from an ExpressJS request.
    24
    // Obtaining this info in a different framework will likely differ
    25
    var username = 'some-user-id',
    26
    sessionId = req.sessionID,
    27
    userAgent = req.get('User-Agent'),
    28
    referrer = req.get('Referrer'),
    29
    remoteAddress = req.headers['x-forwarded-for'] || req.connection.remoteAddress,
    30
    headerKeys = Object.keys(req.headers),
    31
    documentUri = req.protocol + '://' + req.get('Host') + req.originalUrl,
    32
    userValid = false
    33
    TCellHooks.sendLoginEventFailure(
    34
    username,
    35
    sessionId,
    36
    userAgent,
    37
    referrer,
    38
    remoteAddress,
    39
    headerKeys,
    40
    documentUri
    41
    userValid);

API

1
function sendLoginEventSuccess (
2
userId,
3
sessionId,
4
userAgent,
5
referrer,
6
remoteAddress,
7
headerKeys,
8
documentUri) {
9
}
  • userId (string) : Identification used for the user (i.e. email, username)
  • sessionId (string) : (Optional) Session ID for user logging in. This will be HMAC'ed by the Agent before being sent
  • userAgent (string) : Optional) User agent taken from header
  • referrer (string) : (Optional) Referrer taken from header
  • remoteAddress (string) : (Optional) IP of the Request
  • headerKeys (string) : (Optional) An array of the header keys. The order is important (do not sort the array)
  • documentUri (string) : (Optional) Document URI taken from request
1
function sendLoginEventFailure (
2
userId,
3
sessionId,
4
userAgent,
5
referrer,
6
remoteAddress,
7
headerKeys,
8
documentUri,
9
userValid) {
10
}
  • userId (string) : Identification used for the user (i.e. email, username)
  • sessionId (string) : (Optional) Session ID for user logging in. This will be HMAC'ed by the Agent before being sent
  • userAgent (string) : (Optional) User agent taken from header
  • referrer (string) : (Optional) Referrer taken from header
  • remoteAddress (string) : (Optional) IP of the Request
  • headerKeys (string) : (Optional) An array of the header keys. The order is important (do not sort the array)
  • documentUri (string) : (Optional) Document URI taken from request
  • userValid (boolean) : (Optional) Set as true if exists, other false. Defaults to null.
1
function sendExpressLoginEventSuccess (
2
request,
3
userId,
4
sessionId) {
5
}
  • request (object) : Request object provided by ExpressJS
  • userId (string) : Identification used for the user (i.e. email, username)
  • sessionId (string) : (Optional) Session ID for user logging in. This will be HMAC'ed by the Agent before being sent
1
function sendExpressLoginEventFailure (
2
request,
3
userId,
4
sessionId,
5
userValid) {
6
}
  • request (object) : Request object provided by ExpressJS
  • userId (string) : Identification used for the user (i.e. email, username)
  • sessionId (string) : (Optional) Session ID for user logging in. This will be HMAC'ed by the Agent before being sent
  • userValid (boolean) : (Optional) Set as true if exists, other false. Defaults to null.
1
function sendHapiLoginEventSuccess (
2
request,
3
userId,
4
sessionId) {
5
}
  • request (object) : Request object provided by Hapi
  • userId (string) : Identification used for the user (i.e. email, username)
  • sessionId (string) : (Optional) Session ID for user logging in. This will be HMAC'ed by the Agent before being sent
1
function sendHapiLoginEventFailure (
2
request,
3
userId,
4
sessionId,
5
userValid) {
6
}
  • request (object) : Request object provided by Hapi
  • userId (string) : Identification used for the user (i.e. email, username)
  • sessionId (string) : (Optional) Session ID for user logging in. This will be HMAC'ed by the Agent before being sent
  • userValid (boolean) : (Optional) Set as true if exists, other false. Defaults to null.

Password Hash

When you send a secured hashed password to the tCell cloud, you create a more robust Account Takeover response. See Password Hash for more information.

Important

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.