perimeterx-node-core

PerimeterX Shared base for NodeJS enforcers

Latest stable version: v3.15.1

This is a shared base implementation for PerimeterX Express enforcer and future NodeJS enforcers. For a fully functioning implementation example, see the Node-Express enforcer implementation.

Table of Contents

• Usage
  • Installation
  • Basic Usage Example
• Contributing
  • Tests

Installation

$ npm install --save perimeterx-node-core

Basic Usage Example

To integrate this module into an enforcer, users should initialize the enforcer.

function initPXModule(params, client) {
    params.px_module_version = '<your module version>';
    enforcer = new PxEnforcer(params, client);
    //if dynamic configurations is configured
    if (enforcer.config.conf.DYNAMIC_CONFIGURATIONS) {
        setInterval(enforcer.config.confManager.loadData.bind(enforcer.config.confManager), enforcer.config.conf.CONFIGURATION_LOAD_INTERVAL);
    }
}

On every request, call enforce.

/**
 * pxMiddleware - middleware wrapper to score verification.
 *
 * @param {Object} req - HTTP Request.
 * @param {Object} res - HTTP Response.
 * @param {Function} next - callback function.
 */
function pxMiddleware(req, res, next) {
    enforcer.enforce(req, res, (response) => {
        if (response) { //block
            res.status(response.status);
            res.setHeader(response.header.key, response.header.value);
            res.send(response.body);
        } else { //pass
            next();
        }
    });
}

Extend the PxClient class to send activities to PerimeterX.

const { PxClient } = require('perimeterx-node-core');

class MyClient extends PxClient {
    init(config) {
        setInterval(() => {
            this.submitActivities(config);
        }, 1000);
    }
}

module.exports = { MyClient };

Make sure to pass the client instance when initializing the enforcer.

function initPXModule(params) {
    params.px_module_version = '<your module version>';
    const pxClient = new MyClient();
    enforcer = new PxEnforcer(params, pxClient);
    //if dynamic configurations is configured
    if (enforcer.config.conf.DYNAMIC_CONFIGURATIONS) {
        setInterval(enforcer.config.confManager.loadData.bind(enforcer.config.confManager), enforcer.config.conf.CONFIGURATION_LOAD_INTERVAL);
    }
}

Contributing

The following steps are welcome when contributing to our project:

Fork/Clone

First and foremost, Create a fork of the repository, and clone it locally. Create a branch on your fork, preferably using a self descriptive branch name.

Code/Run

Help improve our project by implementing missing features, adding capabilites or fixing bugs.

To run the code, simply follow the steps in the installation guide. Grab the keys from the PerimeterX Portal, and try refreshing your page several times continously. If no default behaviours have been overriden, you should see the PerimeterX block page. Solve the CAPTCHA to clean yourself and start fresh again.

Test

Tests for this project are written using Mocha.

Dont forget to test. The project relies heavily on tests, thus ensuring each user has the same experience, and no new features break the code. Before you create any pull request, make sure your project has passed all tests, and if any new features require it, write your own.

Running tests

$ npm test

Note: running tests without a valid PerimeterX app id, auth token and cookie key will not work.

Pull Request

After you have completed the process, create a pull request to the Upstream repository. Please provide a complete and thorough description explaining the changes. Remember this code has to be read by our maintainers, so keep it simple, smart and accurate.