perimeterx-js-core 0.1.0

package/README.md

@@ -0,0 +1,158 @@
+# PerimeterX JavaScript Core
+
+## Overview
+
+The purpose of this repository is to provide the components and utilities needed to build a JavaScript/TypeScript enforcer
+on any platform/environment. This repository is *not* a complete running enforcer; rather, it is a tool kit with all the
+building blocks that an enforcer comprises, separated into small, self-contained chunks.
+
+A single repository for core enforcer components allows for:
+
+* Consistent functionality across all JavaScript enforcers.
+* Faster delivery of new features and bug fixes.
+
+## Design Principles
+
+This library was designed with an interface-first mindset. In other words, all provided classes are implementations of defined
+interfaces. Whenever possible, you should use the provided, default implementation for a particular feature to ensure consistent
+behavior across enforcers.
+
+However, if the default component cannot be made to function in the framework you are working on, extend it or create a 
+new class that implements the relevant interface, and it will work with all the other components in the library.
+
+### Naming Conventions
+
+* Interfaces always start with the letter `I` (e.g., `IFirstParty`)
+* Abstract classes always end with the word `Base` (e.g., `ContextBase`)
+* Complete, standard implementations start with the word `Default` (e.g., `DefaultTelemetry`)
+* Utility functions relevant to a particular feature live in a `Utils` namespace named for the feature (e.g., `PXHDUtils`)
+
+## Library Components
+
+In using this library, most features will work out-of-the-box. However, there are certain classes you will need to modify
+depending on the specific platform you're developing for.
+
+Most development you will need to complete will most likely be in the following areas.
+
+### Enforcer
+
+While every enforcer will require a different implementation, the API and sequence of events in an enforcer should be consistent
+across different SDKs. To maintain consistency, the following interface and abstract class have been included.
+
+`IEnforcer` - Represents the enforcer itself. The parameters and return values are `any` due to the varying nature of each
+platform. The specific enforcer implementation you create should have a concrete signature.
+
+`EnforcerBase` - An abstract base class that provides the basic enforcer flow with the default building blocks. Select abstract
+functions must be implemented (such as constructing the context, etc.). All key functional building blocks are interfaces 
+that can be swapped out, and modifications to the flow can be made by overriding the protected class methods.
+
+### Configuration
+
+Every enforcer configuration is different. This includes how the configurations are stored (a JSON file, in-memory object,
+or KV namespace), the configuration values themselves, and logging functionality. Utilize these components to simplify
+your enforcer's configuration setup.
+
+`IConfiguration` - Represents the enforcer configuration and is required to construct most other components
+in this library.
+
+`StaticConfigurationBase` - An implementation of the above interface that validates provided configurations and merges
+them with default ones.
+
+`DefaultConfigurations` - A static object complete with all default enforcer configurations.
+
+### Context
+
+Different platforms expose varying levels of information about the HTTP request and server environment. Additionally,
+the cryptographic capabilities on each platform may vary, allowing the support of either V2 or V3 of the Risk Cookie.
+While you will need to create a custom implementation for the request context, you can use these tools to help.
+
+`IContext` - Represents the request context.
+
+`ContextBase` - An implementation of the above interface that takes care of basic context setup.
+
+`DefaultTokenV2Context` - An extension of the above abstract class that creates a `DefaultBotDefenderTokenV2`.
+
+`DefaultTokenV3Context` - An extension of the above abstract class that creates a `DefaultBotDefenderTokenV3`.
+
+### HTTP
+
+Every framework has a different API for creating and sending HTTP requests and responses. This library reduces this functionality
+into three interfaces:
+
+`IHttpRequest` - Represents an HTTP request.
+
+`IHttpResponse` - Represents an HTTP response.
+
+`IHttpClient` - Represents a client that can send an `IHttpRequest` and return an `IHttpResponse`.
+
+When developing your JavaScript/TypeScript enforcer with this library, you will need to wrap the native HTTP request/response
+objects such that they conform to these interfaces. Of course, you are free to extend these interfaces as needed.
+
+The `HttpRequestBase` and `HttpResponseBase` classes are also provided for minimizing code repetition, simplifying
+encapsulating request and response body handling to a single `IBodyReader` interface.
+
+The library also provides the `DefaultHttpRequest` and `DefaultHttpResponse` classes, simple implementations of the
+`IHttpRequest` and `IHttpResponse` interfaces, which are used internally. These implementations use the `StringBodyReader`
+class to parse request and response bodies provided as strings.
+
+You will also need to implement an HTTP client. You can do this however you see fit: use the platform's built-in API
+or use an external library (e.g., `phin`, `axios`) if needed.
+
+### Crypto
+
+Since cryptographic functionality varies from platform to platform, this library's crypto utils takes the form of an interface
+as well. It comes with a specific default implementation.
+
+`IBase64Utils` - Represents a Base64 encoding and decoding utility that other components may require. A `DefaultBase64Utils`
+implementation using the `js-base64` dependency is provided.
+
+`IHashUtils` - Represents an HMAC-generating utility that other components may require. A `DefaultHashUtils`
+implementation using the `crypto-js` dependency is provided.
+
+`ICipherUtils` - Represents an encryption and decryption utility that is required for RiskTokenV3. No default 
+implementation is provided.
+
+### Other Dependencies
+
+All dependencies in this library have been encapsulated into specific implementations with a defined interface and therefore
+can be swapped with other implementations. These classes are:
+
+| **Library**       | **Implementation**        | **Used For**                              |
+| :---              | :---                      | :---                                      |
+| `crypto-js`       | `DefaultHashUtils`        | PXDE, telemetry, risk token V2/V3, etc.   |
+| `js-base64`       | `DefaultBase64Utils`      | PXDE, telemetry, risk token V2, etc.      |
+| `cookie`          | `DefaultCookieParser`     | `ContextBase`                             |
+| `uuid`            | `DefaultUuidGenerator`    | `ContextBase`                             |
+| `ip-range-check`  | `DefaultIpRangeChecker`   | `DefaultFilter`                           |
+
+## For Contributors
+
+### Installing Dependencies
+
+To install dependencies, run:
+
+```shell
+npm install
+```
+
+### Building
+
+To build the module as a library, run:
+
+```shell
+npm run build
+```
+
+### Testing
+
+To run unit tests, run:
+
+```shell
+npm run test
+```
+
+To see unit test coverage, run:
+
+```shell
+npm run coverage
+```

package/lib/activities/ActivityType.d.ts

@@ -0,0 +1,6 @@
+export declare enum ActivityType {
+    PAGE_REQUESTED = "page_requested",
+    BLOCK = "block",
+    ADDITIONAL_S2S = "additional_s2s",
+    ENFORCER_TELEMETRY = "enforcer_telemetry"
+}

package/lib/activities/ActivityType.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ActivityType = void 0;
+var ActivityType;
+(function (ActivityType) {
+    ActivityType["PAGE_REQUESTED"] = "page_requested";
+    ActivityType["BLOCK"] = "block";
+    ActivityType["ADDITIONAL_S2S"] = "additional_s2s";
+    ActivityType["ENFORCER_TELEMETRY"] = "enforcer_telemetry";
+})(ActivityType = exports.ActivityType || (exports.ActivityType = {}));

package/lib/activities/HttpActivityClient.d.ts

@@ -0,0 +1,12 @@
+import { IConfiguration } from '../config';
+import { IContext } from '../context';
+import { IHttpClient } from '../http';
+import { IActivityClient } from './IActivityClient';
+export declare class HttpActivityClient implements IActivityClient {
+    private readonly config;
+    private readonly httpClient;
+    constructor(config: IConfiguration, httpClient: IHttpClient);
+    sendActivities(context: IContext): Promise<boolean>;
+    private createActivities;
+    private postActivities;
+}

package/lib/activities/HttpActivityClient.js

@@ -0,0 +1,107 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
+    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (_) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpActivityClient = void 0;
+var http_1 = require("../http");
+var utils_1 = require("../utils");
+var ActivityType_1 = require("./ActivityType");
+var utils_2 = require("./utils");
+var constants_1 = require("./constants");
+var HttpActivityClient = /** @class */ (function () {
+    function HttpActivityClient(config, httpClient) {
+        this.config = config;
+        this.httpClient = httpClient;
+    }
+    HttpActivityClient.prototype.sendActivities = function (context) {
+        return __awaiter(this, void 0, void 0, function () {
+            var activities, e_1;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        _a.trys.push([0, 2, , 3]);
+                        activities = this.createActivities(context);
+                        return [4 /*yield*/, this.postActivities(activities)];
+                    case 1: return [2 /*return*/, _a.sent()];
+                    case 2:
+                        e_1 = _a.sent();
+                        this.config.logger.error("unable to send activities - ".concat(e_1));
+                        return [2 /*return*/, false];
+                    case 3: return [2 /*return*/];
+                }
+            });
+        });
+    };
+    HttpActivityClient.prototype.createActivities = function (context) {
+        var activities = [];
+        if (context.blockReason) {
+            activities.push((0, utils_2.createActivity)(ActivityType_1.ActivityType.BLOCK, this.config, context));
+        }
+        else if (context.passReason) {
+            activities.push((0, utils_2.createActivity)(ActivityType_1.ActivityType.PAGE_REQUESTED, this.config, context));
+        }
+        return activities;
+    };
+    HttpActivityClient.prototype.postActivities = function (activities) {
+        return __awaiter(this, void 0, void 0, function () {
+            var url, method, headers, body, status;
+            var _a;
+            return __generator(this, function (_b) {
+                switch (_b.label) {
+                    case 0:
+                        url = "".concat(this.config.backendCollectorUrl).concat(constants_1.ACTIVITIES_ENDPOINT);
+                        method = http_1.HttpMethod.POST;
+                        headers = (_a = {},
+                            _a[http_1.CONTENT_TYPE_HEADER_NAME] = [http_1.ContentType.APPLICATION_JSON],
+                            _a[http_1.AUTHORIZATION_HEADER_NAME] = [(0, utils_1.getAuthorizationHeader)(this.config.authToken)],
+                            _a);
+                        body = activities.length === 1 ? JSON.stringify(activities[0]) : JSON.stringify(activities);
+                        this.config.logger.debug("sending ".concat(activities.map(function (_a) {
+                            var type = _a.type;
+                            return "".concat(type, " activity");
+                        }).join(', '), " to ").concat(url));
+                        return [4 /*yield*/, this.httpClient.send(new http_1.DefaultHttpRequest(url, { method: method, headers: headers, body: body }))];
+                    case 1:
+                        status = (_b.sent()).status;
+                        return [2 /*return*/, status === 200];
+                }
+            });
+        });
+    };
+    return HttpActivityClient;
+}());
+exports.HttpActivityClient = HttpActivityClient;

package/lib/activities/IActivityClient.d.ts

@@ -0,0 +1,8 @@
+import { IContext } from '../context';
+export interface IActivityClient {
+    /**
+     * @param context - The request context.
+     * @returns Promise<boolean> - Whether sending the activities was successful or not.
+     */
+    sendActivities(context: IContext): Promise<boolean>;
+}

package/lib/activities/IActivityClient.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/activities/constants.d.ts

@@ -0,0 +1 @@
+export declare const ACTIVITIES_ENDPOINT = "/api/v1/collector/s2s";

package/lib/activities/constants.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ACTIVITIES_ENDPOINT = void 0;
+exports.ACTIVITIES_ENDPOINT = '/api/v1/collector/s2s';

package/lib/activities/index.d.ts

@@ -0,0 +1,5 @@
+export { IActivityClient } from './IActivityClient';
+export { Activity } from './model/Activity';
+export { ActivityTypeDetails, ActivityDetails, BlockActivityDetails, PageRequestedActivityDetails, } from './model/ActivityDetails';
+export { ActivityType } from './ActivityType';
+export { HttpActivityClient } from './HttpActivityClient';

package/lib/activities/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpActivityClient = exports.ActivityType = void 0;
+var ActivityType_1 = require("./ActivityType");
+Object.defineProperty(exports, "ActivityType", { enumerable: true, get: function () { return ActivityType_1.ActivityType; } });
+var HttpActivityClient_1 = require("./HttpActivityClient");
+Object.defineProperty(exports, "HttpActivityClient", { enumerable: true, get: function () { return HttpActivityClient_1.HttpActivityClient; } });

package/lib/activities/model/Activity.d.ts

@@ -0,0 +1,13 @@
+import { ActivityType } from '../ActivityType';
+import { ActivityDetails } from './ActivityDetails';
+export declare type Activity = {
+    type: ActivityType;
+    timestamp: number;
+    socket_ip: string;
+    url: string;
+    px_app_id: string;
+    headers?: Record<string, string | string[]>;
+    vid?: string;
+    pxhd?: string;
+    details: ActivityDetails;
+};

package/lib/activities/model/Activity.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/activities/model/ActivityDetails.d.ts

@@ -0,0 +1,41 @@
+import { PassReason } from '../../utils/PassReason';
+import { BlockReason } from '../../block_handler/BlockReason';
+export declare type ActivityTypeDetails = PageRequestedActivityDetails | BlockActivityDetails | AdditionalS2SActivityDetails;
+export declare type ActivityDetails = ActivityTypeDetails & {
+    client_uuid: string;
+    request_id: string;
+    module_version: string;
+    cookie_origin: string;
+    http_method: string;
+    http_version: string;
+    risk_rtt?: number;
+    request_cookie_names?: string[];
+    server_info_region?: string;
+    tls_protocol?: string;
+    tls_cipher?: string;
+    tls_preferred_ciphers?: string;
+    tls_ciphers_sha?: string;
+    tls_ja3_fingerprint?: string;
+    credentials_compromised?: boolean;
+    ci_version?: string;
+    sso_step?: string;
+};
+export declare type PageRequestedActivityDetails = {
+    pass_reason: PassReason;
+    http_status_code?: number;
+    px_cookie?: string;
+    error_message?: string;
+    s2s_error_reason?: string;
+    s2s_error_http_status?: number;
+};
+export declare type BlockActivityDetails = {
+    block_reason: BlockReason;
+    block_action: string;
+    block_score: string;
+    simulated_block: boolean;
+};
+export declare type AdditionalS2SActivityDetails = {
+    http_status_code: number;
+    login_successful: boolean;
+    raw_username?: string;
+};

package/lib/activities/model/ActivityDetails.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/activities/utils.d.ts

@@ -0,0 +1,10 @@
+import { IContext } from '../context';
+import { IConfiguration } from '../config';
+import { ActivityType } from './ActivityType';
+import { Activity } from './model/Activity';
+import { ActivityDetails, BlockActivityDetails, PageRequestedActivityDetails } from './model/ActivityDetails';
+export declare const createActivity: (activityType: ActivityType, config: IConfiguration, context: IContext) => Activity;
+export declare const createActivityDetails: (activityType: ActivityType, config: IConfiguration, context: IContext) => ActivityDetails;
+export declare const createGenericActivityDetails: (config: IConfiguration, context: IContext) => ActivityDetails;
+export declare const createPageRequestedActivityDetails: (context: IContext) => PageRequestedActivityDetails;
+export declare const createBlockActivityDetails: (context: IContext) => BlockActivityDetails;

package/lib/activities/utils.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createBlockActivityDetails = exports.createPageRequestedActivityDetails = exports.createGenericActivityDetails = exports.createActivityDetails = exports.createActivity = void 0;
+var utils_1 = require("../utils");
+var ActivityType_1 = require("./ActivityType");
+var createActivity = function (activityType, config, context) {
+    return {
+        type: activityType,
+        px_app_id: config.appId,
+        url: context.requestData.url.href,
+        headers: (0, utils_1.removeSensitiveHeaders)(context.requestData.headers, config.sensitiveHeaders).toObject(),
+        pxhd: context.pxhd,
+        socket_ip: context.requestData.ip,
+        timestamp: Date.now(),
+        vid: context.vid,
+        details: (0, exports.createActivityDetails)(activityType, config, context),
+    };
+};
+exports.createActivity = createActivity;
+var createActivityDetails = function (activityType, config, context) {
+    var genericActivityDetails = (0, exports.createGenericActivityDetails)(config, context);
+    var specificActivityDetails = {};
+    switch (activityType) {
+        case ActivityType_1.ActivityType.PAGE_REQUESTED:
+            specificActivityDetails = (0, exports.createPageRequestedActivityDetails)(context);
+            break;
+        case ActivityType_1.ActivityType.BLOCK:
+            specificActivityDetails = (0, exports.createBlockActivityDetails)(context);
+            break;
+        case ActivityType_1.ActivityType.ADDITIONAL_S2S:
+            break;
+    }
+    return Object.assign(genericActivityDetails, specificActivityDetails);
+};
+exports.createActivityDetails = createActivityDetails;
+var createGenericActivityDetails = function (config, context) {
+    var genericActivityDetails = {
+        module_version: config.moduleVersion,
+    };
+    if (context.customParameters) {
+        Object.assign(genericActivityDetails, context.customParameters);
+    }
+    (0, utils_1.transferExistingProperties)(context, genericActivityDetails, {
+        requestId: 'request_id',
+        uuid: 'client_uuid',
+        tokenOrigin: 'cookie_origin',
+    });
+    (0, utils_1.transferExistingProperties)(context.requestData, genericActivityDetails, {
+        httpVersion: 'http_version',
+        method: 'http_method',
+        requestCookieNames: 'request_cookie_names',
+    });
+    (0, utils_1.transferExistingProperties)(context.riskApiData, genericActivityDetails, {
+        riskRtt: 'risk_rtt',
+    });
+    (0, utils_1.transferExistingProperties)(context.serverData, genericActivityDetails, {
+        region: 'server_info_region',
+    });
+    return genericActivityDetails;
+};
+exports.createGenericActivityDetails = createGenericActivityDetails;
+var createPageRequestedActivityDetails = function (context) {
+    var details = {};
+    (0, utils_1.transferExistingProperties)(context, details, {
+        passReason: 'pass_reason',
+    });
+    (0, utils_1.transferExistingProperties)(context.riskApiData, details, {
+        s2sErrorReason: 's2s_error_reason',
+        s2sErrorHttpStatus: 's2s_error_http_status',
+        errorMessage: 'error_message',
+    });
+    (0, utils_1.transferExistingProperties)(context.responseData, details, {
+        status: 'http_status_code',
+    });
+    return details;
+};
+exports.createPageRequestedActivityDetails = createPageRequestedActivityDetails;
+var createBlockActivityDetails = function (context) {
+    var details = {};
+    (0, utils_1.transferExistingProperties)(context, details, {
+        blockReason: 'block_reason',
+        blockAction: 'block_action',
+        score: 'block_score',
+        isMonitoredRequest: 'simulated_block',
+    });
+    return details;
+};
+exports.createBlockActivityDetails = createBlockActivityDetails;

package/lib/additional_activity_handler/AdditionalActivityHandler.d.ts

@@ -0,0 +1,3 @@
+import { ConfigurationParams } from '../config';
+import { IContext } from '../context';
+export declare type AdditionalActivityHandler = (config: ConfigurationParams, context: IContext) => void | Promise<void>;

package/lib/additional_activity_handler/AdditionalActivityHandler.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/additional_activity_handler/AdditionalActivityHandlerUtils.d.ts

@@ -0,0 +1,5 @@
+import { IContext } from '../context';
+import { IConfiguration } from '../config';
+export declare namespace AdditionalActivityHandlerUtils {
+    const invokeAdditionalActivityHandler: (config: IConfiguration, context: IContext) => Promise<void>;
+}

package/lib/additional_activity_handler/AdditionalActivityHandlerUtils.js

@@ -0,0 +1,64 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
+    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (_) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AdditionalActivityHandlerUtils = void 0;
+var AdditionalActivityHandlerUtils;
+(function (AdditionalActivityHandlerUtils) {
+    var _this = this;
+    AdditionalActivityHandlerUtils.invokeAdditionalActivityHandler = function (config, context) { return __awaiter(_this, void 0, void 0, function () {
+        var e_1;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    if (!(config.additionalActivityHandler && typeof config.additionalActivityHandler === 'function')) return [3 /*break*/, 4];
+                    _a.label = 1;
+                case 1:
+                    _a.trys.push([1, 3, , 4]);
+                    return [4 /*yield*/, config.additionalActivityHandler(config.toParams(), context)];
+                case 2:
+                    _a.sent();
+                    return [3 /*break*/, 4];
+                case 3:
+                    e_1 = _a.sent();
+                    config.logger.error("caught additional activity handler error - ".concat(e_1));
+                    return [3 /*break*/, 4];
+                case 4: return [2 /*return*/];
+            }
+        });
+    }); };
+})(AdditionalActivityHandlerUtils = exports.AdditionalActivityHandlerUtils || (exports.AdditionalActivityHandlerUtils = {}));

package/lib/additional_activity_handler/index.d.ts

@@ -0,0 +1,2 @@
+export { AdditionalActivityHandler } from './AdditionalActivityHandler';
+export { AdditionalActivityHandlerUtils } from './AdditionalActivityHandlerUtils';

package/lib/additional_activity_handler/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AdditionalActivityHandlerUtils = void 0;
+var AdditionalActivityHandlerUtils_1 = require("./AdditionalActivityHandlerUtils");
+Object.defineProperty(exports, "AdditionalActivityHandlerUtils", { enumerable: true, get: function () { return AdditionalActivityHandlerUtils_1.AdditionalActivityHandlerUtils; } });

package/lib/block_handler/BlockAction.d.ts

@@ -0,0 +1,6 @@
+export declare enum BlockAction {
+    CAPTCHA = "c",
+    RATE_LIMIT = "r",
+    CHALLENGE = "j"
+}
+export declare const blockActionToWord: (blockAction: BlockAction) => string;

package/lib/block_handler/BlockAction.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.blockActionToWord = exports.BlockAction = void 0;
+var BlockAction;
+(function (BlockAction) {
+    BlockAction["CAPTCHA"] = "c";
+    BlockAction["RATE_LIMIT"] = "r";
+    BlockAction["CHALLENGE"] = "j";
+})(BlockAction = exports.BlockAction || (exports.BlockAction = {}));
+var blockActionToWord = function (blockAction) {
+    switch (blockAction) {
+        case BlockAction.RATE_LIMIT:
+            return 'ratelimit';
+        case BlockAction.CHALLENGE:
+            return 'challenge';
+        case BlockAction.CAPTCHA:
+        default:
+            return 'captcha';
+    }
+};
+exports.blockActionToWord = blockActionToWord;

package/lib/block_handler/BlockReason.d.ts

@@ -0,0 +1,4 @@
+export declare enum BlockReason {
+    S2S_HIGH_SCORE = "s2s_high_score",
+    COOKIE_HIGH_SCORE = "cookie_high_score"
+}

package/lib/block_handler/BlockReason.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BlockReason = void 0;
+var BlockReason;
+(function (BlockReason) {
+    BlockReason["S2S_HIGH_SCORE"] = "s2s_high_score";
+    BlockReason["COOKIE_HIGH_SCORE"] = "cookie_high_score";
+})(BlockReason = exports.BlockReason || (exports.BlockReason = {}));