perimeterx-js-core 0.24.4 → 0.26.0

package/lib/esm/context/DefaultContext.js

@@ -1,4 +1,3 @@
-import { RemoteConfigUtils } from '../config/index.js';
 import { BlockAction } from '../blocker/index.js';
 import { PXHDSource } from '../pxhd/index.js';
 import { TokenOrigin, TokenParseResult } from '../risk_token/index.js';
@@ -7,11 +6,14 @@ import { COOKIE_HEADER_NAME, toReadonlyHeaders, USER_AGENT_HEADER_NAME, } from '
 import { isValidUuid, PXHD_COOKIE_NAME, PXVID_COOKIE_NAME, StringSplitCookieParser, X_PX_AUTHORIZATION_HEADER_NAME, } from '../utils/index.js';
 import { Action } from '../action/index.js';
 import { DefaultLogger, X_PX_ENFORCER_LOG_HEADER } from '../logger/index.js';
+/**
+ * The default implementation of the request context which uses the incoming HTTP request and enforcer configuration
+ * to populate the context with relevant data.
+ */
 export class DefaultContext {
     requestId;
     tokenOrigin;
-    isRemoteConfigUpdateRequest;
-    shouldSendLogs;
+    remoteConfigUpdateData;
     requestData;
     tokenData;
     riskApiData;
@@ -35,6 +37,7 @@ export class DefaultContext {
     logger;
     usedCookieSecret;
     shouldSendTelemetry;
+    _shouldSendLogs = false;
     config;
     urlUtils;
     constructor(config, request, options) {
@@ -55,8 +58,10 @@ export class DefaultContext {
         this.pxdeVerified = false;
         this.action = Action.TRIGGER_RISK_API;
         this.reasons = {};
-        this.isRemoteConfigUpdateRequest = RemoteConfigUtils.isRemoteConfigUpdateRequest(request);
-        this.shouldSendLogs = this.isRemoteConfigUpdateRequest || this.isHeaderBasedLoggerRequest(config, request);
+        this.remoteConfigUpdateData = {
+            shouldUpdate: false,
+        };
+        this.shouldSendLogs = this.isHeaderBasedLoggerRequest(config, request);
         this.logger = this.createContextLogger(config, this.shouldSendLogs);
         this.requestData = this.createRequestData(config, request, options.cookieParser);
         this.tokenOrigin = this.getTokenOrigin(request);
@@ -65,6 +70,18 @@ export class DefaultContext {
         }
         this.shouldSendTelemetry = false;
     }
+    get shouldSendLogs() {
+        return this._shouldSendLogs;
+    }
+    set shouldSendLogs(shouldSendLogs) {
+        if (this._shouldSendLogs === shouldSendLogs) {
+            return;
+        }
+        this._shouldSendLogs = shouldSendLogs;
+        if (this.logger) {
+            this.logger.shouldSaveLogs = shouldSendLogs;
+        }
+    }
     get isMobile() {
         return this.tokenOrigin === TokenOrigin.HEADER;
     }
@@ -152,7 +169,7 @@ export class DefaultContext {
             action: this.action,
             reasons: this.reasons,
             isMobile: this.isMobile,
-            isRemoteConfigUpdateRequest: this.isRemoteConfigUpdateRequest,
+            remoteConfigUpdateData: this.remoteConfigUpdateData,
             productData: this.productData,
             requestData: {
                 ...this.requestData,

package/lib/esm/context/SerializedContext.js

@@ -1,9 +1,14 @@
 import { DefaultLogger } from '../logger/index.js';
 import { SerializedToken } from '../risk_token/index.js';
 import { SerializedRiskResponse } from '../risk_api/index.js';
+/**
+ * Implements the `IContext` interface based an already serialized `ContextJson`. This class does not extract data from the
+ * incoming request, but rather uses already-extracted data from the `ContextJson` (likely returned from the `DefaultContext.toJSON()`
+ * function) and fills in the gaps using the other parameters.
+ */
 export class SerializedContext {
     isMobile;
-    isRemoteConfigUpdateRequest;
+    remoteConfigUpdateData;
     logger;
     productData;
     requestData;
@@ -33,7 +38,7 @@ export class SerializedContext {
         this.reasons = contextJson.reasons;
         this.isMobile = contextJson.isMobile;
         this.requestId = contextJson.requestId;
-        this.isRemoteConfigUpdateRequest = contextJson.isRemoteConfigUpdateRequest;
+        this.remoteConfigUpdateData = contextJson.remoteConfigUpdateData;
         this.logger = this.createLogger(config, contextJson.shouldSendLogs, contextJson.logger?.logs);
         this.productData = contextJson.productData;
         this.requestData = this.createRequestData(contextJson, request, urlUtils);

package/lib/esm/context/interfaces/RemoteConfigUpdateData.js

@@ -0,0 +1 @@
+export {};

package/lib/esm/context/interfaces/index.js

@@ -4,5 +4,6 @@ export * from './MobileData.js';
 export * from './TokenData.js';
 export * from './TlsData.js';
 export * from './ServerData.js';
+export * from './RemoteConfigUpdateData.js';
 export * from './IContext.js';
 export * from './ReadonlyContext.js';

package/lib/esm/enforcer/EnforcerBase.js

@@ -1,5 +1,8 @@
-import { EndEnforcerFlow, EnforceFlow, FilterFlow, PostEnforceFlow } from '../phase/index.js';
+import { EndEnforcerFlow, EnforceFlow, FilterFlow, PostEnforceFlow } from '../flow/index.js';
 import { createEnforcerInitializationBlock } from './utils.js';
+/**
+ * The base class for fundamental enforcer logic.
+ */
 export class EnforcerBase {
     config;
     filterFlow;
@@ -7,6 +10,7 @@ export class EnforcerBase {
     postEnforceFlow;
     endEnforcerFlow;
     activityClient;
+    remoteConfigManager;
     /**
      * The EnforcerBase constructor.
      * @param config - The enforcer configuration.
@@ -17,6 +21,7 @@ export class EnforcerBase {
         this.config = config;
         const initializationBlock = createEnforcerInitializationBlock(config, options);
         this.activityClient = initializationBlock.activityClient;
+        this.remoteConfigManager = initializationBlock.remoteConfigManager;
         this.filterFlow = this.createFilterFlow(config, initializationBlock);
         this.enforceFlow = this.createEnforceFlow(config, initializationBlock);
         this.postEnforceFlow = this.createPostEnforceFlow(config, initializationBlock);
@@ -25,15 +30,47 @@ export class EnforcerBase {
             this.config.logger.debug('HUMAN enforcer is disabled, will not enforce');
         }
     }
+    /**
+     * Creates the filter flow for the enforcer. The filter flow is responsible for filtering out requests that should not undergo the usual enforcement flow.
+     * For example, first party, filtered, CORS preflight, and telemetry requests are filtered out.
+     * @param config - The configuration object.
+     * @param initializationBlock - All entities necessary for the enforcer to function.
+     * @protected
+     * @returns - The filter flow for the enforcer.
+     */
     createFilterFlow(config, initializationBlock) {
         return new FilterFlow(config, initializationBlock);
     }
+    /**
+     * Creates the post enforce flow for the enforcer. The post enforce flow is responsible for any logic that requires the origin response in the case of passed requests.
+     * For example, enriching the context with response data (status, login successful information) and modifying the origin response (snippet injection, PXHD) are part of the post enforce flow.
+     * @param config - The configuration object.
+     * @param initializationBlock - All entities necessary for the enforcer to function.
+     * @protected
+     * @returns - The post enforce flow for the enforcer or null if post enforce is not enabled.
+     */
     createPostEnforceFlow(config, initializationBlock) {
-        return new PostEnforceFlow(config, initializationBlock);
+        return this.config.isPostEnforceEnabled ? new PostEnforceFlow(config, initializationBlock) : null;
     }
+    /**
+     * Creates the enforce flow for the enforcer. The enforce flow is responsible for the core functionality of HUMAN enforcement.
+     * For example, parsing HUMAN cookies, performing Risk API, invoking the additional activity handler, and returning a block response are part of the enforce flow.
+     * @param config - The configuration object.
+     * @param initializationBlock - All entities necessary for the enforcer to function.
+     * @protected
+     * @returns - The enforce flow for the enforcer.
+     */
     createEnforceFlow(config, initializationBlock) {
         return new EnforceFlow(config, initializationBlock);
     }
+    /**
+     * Creates the end enforce flow for the enforcer. The end enforce flow is responsible for all actions that must be done after every incoming request.
+     * For example, sending the async activities, sending the telemetry activity, or updating the remote config, sending and clearing the enforcer logs, are parts of the end enforce flow.
+     * @param config - The configuration object.
+     * @param initializationBlock - All entities necessary for the enforcer to function.
+     * @protected
+     * @returns - The end enforce flow for the enforcer.
+     */
     createEndEnforcerFlow(config, initializationBlock) {
         return new EndEnforcerFlow(config, initializationBlock);
     }
@@ -43,6 +80,7 @@ export class EnforcerBase {
      * @returns Promise<Res|null> - A Promise resolving to a Res or null depending on the action that should be taken.
      */
     async enforce(...args) {
+        await this.remoteConfigManager?.loadRemoteConfig();
         let context;
         try {
             if (!this.config.moduleEnabled) {
@@ -69,12 +107,14 @@ export class EnforcerBase {
             await this.endEnforcerFlow.execute(context);
             return result.response ? this.convertToRes(result.response, ...args) : null;
         }
-        await this.preserveContext(context, ...args);
         result = await this.enforceFlow.execute(context);
-        if (result.done) {
+        if (result.done || !this.config.isPostEnforceEnabled) {
             await this.endEnforcerFlow.execute(context);
             return result.response ? this.convertToRes(result.response, ...args) : null;
         }
+        if (this.config.isPostEnforceEnabled) {
+            await this.preserveContext(context, ...args);
+        }
         return null;
     }
     /**
@@ -85,13 +125,13 @@ export class EnforcerBase {
     async postEnforce(...args) {
         let context;
         try {
-            if (!this.config.moduleEnabled) {
+            if (!this.config.moduleEnabled || !this.config.isPostEnforceEnabled) {
                 return;
             }
             context = this.retrieveContext(...args);
             if (context) {
                 context.response = await this.convertToOutgoingResponse(...args);
-                await this.postEnforceFlow.execute(context);
+                await this.postEnforceFlow?.execute(context);
                 await this.endEnforcerFlow.execute(context);
             }
         }

package/lib/esm/enforcer/IPostEnforcer.js

@@ -0,0 +1 @@
+export {};

package/lib/esm/enforcer/index.js

@@ -1,4 +1,5 @@
 export * from './IEnforcer.js';
+export * from './IPostEnforcer.js';
 export * from './EnforcerBase.js';
 export * from './EnforcerOptions.js';
 export * from './utils.js';

package/lib/esm/enforcer/utils.js

@@ -1,5 +1,5 @@
 import { DefaultTokenV2Parser, DefaultTokenV3Parser, TokenVersion } from '../risk_token/index.js';
-import { DefaultRemoteConfigUpdater, HttpRemoteConfigServiceClient } from '../config/index.js';
+import { DefaultNotifyRemoteConfigUpdateParser, DefaultRemoteConfigManager, HttpRemoteConfigServiceClient, } from '../config/index.js';
 import { DefaultCors } from '../cors/index.js';
 import { DefaultTelemetry } from '../telemetry/index.js';
 import { DefaultDataEnrichment } from '../pxde/index.js';
@@ -17,7 +17,7 @@ export const createEnforcerInitializationBlock = (config, options) => {
             .map((v) => `"${v}"`)
             .join(', ')})`);
     }
-    const cipherUtils = tokenVersion === TokenVersion.V2 ? null : options.cipherUtils ?? null;
+    const cipherUtils = tokenVersion === TokenVersion.V2 ? null : (options.cipherUtils ?? null);
     if (tokenVersion === TokenVersion.V3 && !cipherUtils) {
         throw new EnforcerError('error initializing enforcer: token v3 requires cipherUtils');
     }
@@ -39,20 +39,9 @@ export const createEnforcerInitializationBlock = (config, options) => {
             ? new HttpBatchedActivityClient(config, httpClient)
             : new HttpActivityClient(config, httpClient));
     const logServiceClient = options.logServiceClient || (config.loggerAuthToken ? new HttpLogServiceClient(config, httpClient) : null);
-    const remoteConfigStorageClient = options.remoteConfigStorageClient ?? null;
-    const remoteConfigServiceClient = options.remoteConfigServiceClient ||
-        (config.remoteConfigAuthToken ? new HttpRemoteConfigServiceClient(config, httpClient) : null);
-    const remoteConfigUpdater = options.remoteConfigUpdater ||
-        (remoteConfigStorageClient && remoteConfigServiceClient
-            ? new DefaultRemoteConfigUpdater(config, {
-                serviceClient: remoteConfigServiceClient,
-                storageClient: remoteConfigStorageClient,
-                base64Utils,
-                hmacUtils,
-            })
-            : null);
     const snippetInjector = options.snippetInjector ?? null;
     const snippetRetriever = options.snippetRetriever || (snippetInjector ? new DefaultSnippetRetriever(config) : null);
+    const remoteConfigClients = createRemoteConfigClients(config, options);
     const allOptions = {
         httpClient,
         base64Utils,
@@ -69,11 +58,9 @@ export const createEnforcerInitializationBlock = (config, options) => {
         riskApiClient,
         activityClient,
         logServiceClient,
-        remoteConfigStorageClient,
-        remoteConfigServiceClient,
-        remoteConfigUpdater,
         snippetInjector,
         snippetRetriever,
+        ...remoteConfigClients,
     };
     const products = createEnforcerProducts(config, options.products, base64Utils, hashUtils, urlUtils, ipRangeChecker);
     return { products, ...allOptions };
@@ -93,3 +80,31 @@ export const createEnforcerProducts = (config, products, base64Utils, hashUtils,
         [ProductName.HYPE_SALE_CHALLENGE]: hypeSaleChallenge,
     };
 };
+export const createRemoteConfigClients = (config, options) => {
+    const remoteConfigStorageClient = options.remoteConfigStorageClient ?? null;
+    let remoteConfigServiceClient = null;
+    let remoteConfigManager = null;
+    let remoteConfigUpdateParser = null;
+    if (remoteConfigStorageClient) {
+        remoteConfigServiceClient =
+            options.remoteConfigServiceClient ?? new HttpRemoteConfigServiceClient(config, options.httpClient);
+        remoteConfigManager =
+            options.remoteConfigManager ??
+                new DefaultRemoteConfigManager(config, {
+                    serviceClient: remoteConfigServiceClient,
+                    storageClient: remoteConfigStorageClient,
+                });
+        remoteConfigUpdateParser =
+            options.remoteConfigUpdateParser ??
+                new DefaultNotifyRemoteConfigUpdateParser(config, {
+                    base64Utils: options.base64Utils,
+                    hmacUtils: options.hmacUtils,
+                });
+    }
+    return {
+        remoteConfigServiceClient,
+        remoteConfigManager,
+        remoteConfigUpdateParser,
+        remoteConfigStorageClient,
+    };
+};

package/lib/esm/flow/EndEnforcerFlow.js

@@ -0,0 +1,18 @@
+import { ClearLogsPhase, SendLogsPhase, SendTelemetryActivityPhase, UpdateRemoteConfigPhase, SendAsyncActivitiesPhase, } from '../phase/index.js';
+import { Flow } from './Flow.js';
+export class EndEnforcerFlow extends Flow {
+    constructor(config, { logServiceClient, telemetry, remoteConfigManager, activityClient, }) {
+        const phases = [
+            new SendAsyncActivitiesPhase(activityClient),
+            new SendTelemetryActivityPhase(telemetry),
+        ];
+        if (remoteConfigManager) {
+            phases.push(new UpdateRemoteConfigPhase(config, remoteConfigManager));
+        }
+        if (logServiceClient) {
+            phases.push(new SendLogsPhase(config, logServiceClient));
+        }
+        phases.push(new ClearLogsPhase());
+        super(phases);
+    }
+}

package/lib/esm/flow/EnforceFlow.js

@@ -0,0 +1,14 @@
+import { AdditionalActivityHandlerPhase, CreateBlockResponsePhase, EnrichContextFromRequestPhase, ModifyIncomingRequestPhase, ParseTokenPhase, RiskApiPhase, } from '../phase/index.js';
+import { Flow } from './Flow.js';
+export class EnforceFlow extends Flow {
+    constructor(config, { dataEnrichment, tokenParser, riskApiClient, cors, products, graphQLParser, }) {
+        super([
+            new ParseTokenPhase(tokenParser),
+            new EnrichContextFromRequestPhase(config, products, dataEnrichment, graphQLParser),
+            new RiskApiPhase(products, riskApiClient),
+            new AdditionalActivityHandlerPhase(config),
+            new CreateBlockResponsePhase(config, CreateBlockResponsePhase.getBlockers(products), cors),
+            new ModifyIncomingRequestPhase(Object.values(products)),
+        ]);
+    }
+}

package/lib/esm/{phase/flow → flow}/FilterFlow.js

@@ -1,8 +1,9 @@
-import { ProductName } from '../../products/index.js';
-import { isNullOrUndefined } from '../../utils/index.js';
-import { CompositePhase, FilterPhase, FirstPartyPhase, PreflightPhase, UpdateRemoteConfigPhase, IdentifyTelemetryRequestPhase, } from '../impl/index.js';
-export class FilterFlow extends CompositePhase {
-    constructor(config, { httpClient, products, cors, telemetry, remoteConfigUpdater, }) {
+import { ProductName } from '../products/index.js';
+import { isNullOrUndefined } from '../utils/index.js';
+import { FilterPhase, FirstPartyPhase, PreflightPhase, IdentifyTelemetryRequestPhase, IdentifyRemoteConfigNotifyRequestPhase, } from '../phase/index.js';
+import { Flow } from './Flow.js';
+export class FilterFlow extends Flow {
+    constructor(config, { httpClient, products, cors, telemetry, remoteConfigUpdateParser, }) {
         const phases = [];
         const firstPartyProducts = FilterFlow.getFirstPartyProducts(products);
         if (firstPartyProducts?.length > 0) {
@@ -14,9 +15,8 @@ export class FilterFlow extends CompositePhase {
         }
         phases.push(new PreflightPhase(config, cors));
         phases.push(new IdentifyTelemetryRequestPhase(telemetry));
-        if (remoteConfigUpdater) {
-            const updateRemoteConfigPhase = new UpdateRemoteConfigPhase(config, remoteConfigUpdater);
-            phases.push(updateRemoteConfigPhase);
+        if (remoteConfigUpdateParser) {
+            phases.push(new IdentifyRemoteConfigNotifyRequestPhase(remoteConfigUpdateParser));
         }
         super(phases);
     }

package/lib/esm/flow/Flow.js

@@ -0,0 +1,56 @@
+import { CompositePhase } from '../phase/index.js';
+export class Flow {
+    phases;
+    constructor(phases) {
+        this.phases = phases;
+    }
+    insert(phase, options) {
+        if (!options) {
+            this.phases.push(phase);
+            return;
+        }
+        if (options.before) {
+            const index = this.getIndexOfPhase(options.before);
+            if (index === -1) {
+                return;
+            }
+            this.phases.splice(index, 0, phase);
+        }
+        if (options.after) {
+            const index = this.getIndexOfPhase(options.after);
+            if (index === -1) {
+                return;
+            }
+            this.phases.splice(index + 1, 0, phase);
+        }
+    }
+    remove(name) {
+        const index = this.getIndexOfPhase(name);
+        if (index === -1) {
+            return;
+        }
+        this.phases.splice(index, 1);
+    }
+    replace(name, phase) {
+        const index = this.getIndexOfPhase(name);
+        if (index === -1) {
+            return;
+        }
+        this.phases.splice(index, 1, phase);
+    }
+    move(name, to) {
+        const index = this.getIndexOfPhase(name);
+        if (index === -1) {
+            return;
+        }
+        const phase = this.phases[index];
+        this.phases.splice(index, 1);
+        this.insert(phase, to);
+    }
+    getIndexOfPhase(name) {
+        return this.phases.findIndex((existingPhase) => existingPhase.constructor.name === name);
+    }
+    execute(context) {
+        return new CompositePhase(this.phases).execute(context);
+    }
+}

package/lib/esm/flow/IFlow.js

@@ -0,0 +1 @@
+export {};

package/lib/esm/flow/PostEnforceFlow.js

@@ -0,0 +1,10 @@
+import { EnrichContextFromResponsePhase, ModifyOutgoingResponsePhase } from '../phase/index.js';
+import { Flow } from './Flow.js';
+export class PostEnforceFlow extends Flow {
+    constructor(config, { products, snippetRetriever, snippetInjector, }) {
+        super([
+            new EnrichContextFromResponsePhase(config, products),
+            new ModifyOutgoingResponsePhase(config, Object.values(products), snippetRetriever, snippetInjector),
+        ]);
+    }
+}

package/lib/esm/{phase/flow → flow}/index.js

@@ -2,3 +2,5 @@ export * from './FilterFlow.js';
 export * from './EnforceFlow.js';
 export * from './PostEnforceFlow.js';
 export * from './EndEnforcerFlow.js';
+export * from './IFlow.js';
+export * from './Flow.js';

package/lib/esm/index.js

@@ -9,6 +9,7 @@ export * from './sensitive_request/index.js';
 export * from './monitored_request/index.js';
 export * from './snippet_injection/index.js';
 export * from './cors/index.js';
+export * from './flow/index.js';
 export * from './enforcer/index.js';
 export * from './filter/index.js';
 export * from './first_party/index.js';

package/lib/esm/logger/LoggerBase.js

@@ -1,7 +1,7 @@
 import { LoggerSeverity } from './LoggerSeverity.js';
 export class LoggerBase {
-    loggerSeverity;
     shouldSaveLogs;
+    loggerSeverity;
     logs;
     constructor(loggerSeverity = LoggerSeverity.ERROR, shouldSaveLogs, logs = []) {
         this.loggerSeverity = loggerSeverity;

package/lib/esm/phase/impl/AdditionalActivityHandlerPhase.js

@@ -1,4 +1,7 @@
 import { AdditionalActivityHandlerUtils } from '../../additional_activity_handler/index.js';
+/**
+ * The `AdditionalActivityHandlerPhase` invokes the additional activity handler defined in the configuration.
+ */
 export class AdditionalActivityHandlerPhase {
     config;
     constructor(config) {

package/lib/esm/phase/impl/ClearLogsPhase.js

@@ -1,3 +1,6 @@
+/**
+ * The `ClearLogsPhase` class deletes the context logs to free up memory.
+ */
 export class ClearLogsPhase {
     async execute(context) {
         context.logger.clearLogs();

package/lib/esm/phase/impl/CompositePhase.js

@@ -1,5 +1,14 @@
+/**
+ * The `CompositePhase` class executes a series of phases in sequence.
+ * It will stop executing phases as soon as one of them returns a result with `done: true`.
+ * It will return the result of the last phase executed or `{ done: false }`.
+ */
 export class CompositePhase {
     phases;
+    /**
+     * Creates a new CompositePhase instance.
+     * @param phases - An array of phases to be executed in sequence.
+     */
     constructor(phases) {
         this.phases = phases;
     }

package/lib/esm/phase/impl/CreateBlockResponsePhase.js

@@ -1,7 +1,11 @@
 import { MinimalResponseUtils } from '../../http/index.js';
 import { PXHDSource, PXHDUtils } from '../../pxhd/index.js';
 import { Action } from '../../action/index.js';
-import { PRODUCT_PRIORITY_ORDER } from '../../products/index.js';
+import { PRODUCT_PRIORITY_ORDER, ProductName } from '../../products/index.js';
+/**
+ * `CreateBlockResponsePhase` is a phase that creates a block response for the product that recommended a block action.
+ * If multiple products recommended block, it will return the block response for the highest priority product.
+ */
 export class CreateBlockResponsePhase {
     config;
     blockers;
@@ -13,6 +17,17 @@ export class CreateBlockResponsePhase {
             this.cors = cors;
         }
     }
+    /**
+     * A static method that identifies those products that can block incoming requests and returns a map of the product name to the product instance.
+     * @param products - All supported products.
+     * @returns A mapping of those products that implement the `IConditionalBlocker` interface.
+     */
+    static getBlockers(products) {
+        return {
+            [ProductName.BOT_DEFENDER]: products[ProductName.BOT_DEFENDER],
+            [ProductName.HYPE_SALE_CHALLENGE]: products[ProductName.HYPE_SALE_CHALLENGE],
+        };
+    }
     async execute(context) {
         if (context.action !== Action.BLOCK) {
             return { done: false };

package/lib/esm/phase/impl/DecideActionPhase.js

@@ -1,7 +1,18 @@
 import { LoggerSeverity } from '../../logger/index.js';
 import { Action, getDecisionFromContext } from '../../action/index.js';
 import { BlockAction } from '../../blocker/index.js';
+/**
+ * `DecideActionPhase` is an abstract class that provides the protected function `updateContextDecision`.
+ * Phases that extend this class can use the `updateContextDecision` method to update the `context.action` and
+ * `context.reasons` properties based on the product data in the context. Calling this function essentially
+ * recalculates what action the enforcer should take and why.
+ */
 export class DecideActionPhase {
+    /**
+     * Updates the `action`, `reasons`, and `blockAction` properties based on the product data in the context.
+     * @param context - The request context.
+     * @protected
+     */
     async updateContextDecision(context) {
         const { action, reasons } = getDecisionFromContext(context);
         if (context.logger.getLoggerSeverity() === LoggerSeverity.DEBUG) {

package/lib/esm/phase/impl/EnrichContextFromRequestPhase.js

@@ -1,5 +1,14 @@
 import { CustomParametersUtils } from '../../custom_parameters/index.js';
 import { DecideActionPhase } from './DecideActionPhase.js';
+/**
+ * `EnrichContextFromRequestPhase` adds data to the context from the request. This includes parsing the data enrichment cookie,
+ * adding GraphQL data, custom parameters, and enriching the context with any product-specific data by calling each product's
+ * `enrichContextFromRequest` method. (As an example, this is where the Credential Intelligence product enriches the context by
+ * extracting login credentials and adding them to the product data of the request.) It then updates the context's final action
+ * and reasons based on the enriched data.
+ *
+ * Note: This phase should come after the `ParseTokenPhase`, since the Bot Defender product uses the parsed token to determine its recommended action.
+ */
 export class EnrichContextFromRequestPhase extends DecideActionPhase {
     config;
     products;

package/lib/esm/phase/impl/EnrichContextFromResponsePhase.js

@@ -1,4 +1,8 @@
 import { isNullOrUndefined } from '../../utils/index.js';
+/**
+ * `EnrichContextFromResponsePhase` enriches the context with response data. Each product's `enrichContextFromResponse`
+ * method is called since every product may use the response data differently.
+ */
 export class EnrichContextFromResponsePhase {
     config;
     products;

package/lib/esm/phase/impl/FilterPhase.js

@@ -1,3 +1,7 @@
+/**
+ * The `FilterPhase` class checks if the provided filters indicate that the incoming HTTP request should be filtered from the flow.
+ * If any filter returns `true` for `shouldFilter`, the phase will stop further processing and return a `done` status.
+ */
 export class FilterPhase {
     filters;
     constructor(filters) {

package/lib/esm/phase/impl/FirstPartyPhase.js

@@ -1,4 +1,9 @@
 import { MinimalResponseUtils } from '../../http/index.js';
+/**
+ * The `FirstPartyPhase` class is responsible for handling first-party requests. If a first-party request is detected,
+ * it will create the `FirstPartyData`, send the request to the configured endpoint using the provided HTTP client, and return
+ * a done status with the response. If an error occurs, it will return the default response.
+ */
 export class FirstPartyPhase {
     config;
     httpClient;

package/lib/esm/phase/impl/IdentifyRemoteConfigNotifyRequestPhase.js

@@ -0,0 +1,29 @@
+import { MinimalResponseImpl } from '../../http/index.js';
+/**
+ * The `IdentifyRemoteConfigNotifyRequestPhase` class is responsible for identifying incoming remote config update requests.
+ * It checks if the request is a remote config update request and, if so, parses the request and updates the context accordingly.
+ * Note that the remote config is not updated during this phase; that occurs in the `UpdateRemoteConfigPhase`.
+ */
+export class IdentifyRemoteConfigNotifyRequestPhase {
+    remoteConfigUpdateParser;
+    constructor(remoteConfigUpdateParser) {
+        this.remoteConfigUpdateParser = remoteConfigUpdateParser;
+    }
+    async execute(context) {
+        if (!(await this.remoteConfigUpdateParser.isUpdateRequest(context))) {
+            return { done: false };
+        }
+        context.shouldSendLogs = true;
+        const { shouldUpdate, desiredVersion } = await this.remoteConfigUpdateParser.parseUpdate(context);
+        context.remoteConfigUpdateData.shouldUpdate = shouldUpdate;
+        context.remoteConfigUpdateData.desiredVersion = desiredVersion;
+        return {
+            done: true,
+            response: new MinimalResponseImpl({
+                status: shouldUpdate ? 200 : 400,
+                body: shouldUpdate ? 'OK' : 'Bad Request',
+                headers: {},
+            }),
+        };
+    }
+}

package/lib/esm/phase/impl/IdentifyTelemetryRequestPhase.js

@@ -1,3 +1,8 @@
+/**
+ * The `IdentifyTelemetryRequestPhase` class is responsible for identifying incoming telemetry requests.
+ * It checks if the request is a telemetry request and, if so, parses the request and updates the context accordingly.
+ * Note that the telemetry activity is not sent during this phase; that occurs in the `SendTelemetryActivityPhase`.
+ */
 export class IdentifyTelemetryRequestPhase {
     telemetry;
     constructor(telemetry) {

package/lib/esm/phase/impl/ModifyIncomingRequestPhase.js

@@ -1,3 +1,8 @@
+/**
+ * The `ModifyIncomingRequestPhase` class is responsible for modifying the incoming HTTP request prior to forwarding the
+ * request to the origin server or cache. This phase invokes each product's `modifyIncomingRequest` method. (As an example,
+ * this is where the Credential Intelligence product adds the compromised credentials header to the request if needed.)
+ */
 export class ModifyIncomingRequestPhase {
     products;
     constructor(products) {