> This page is for Applications Protection. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.humansecurity.com/llms.txt. # Netlify Edge Function Enforcer configurations ## Overview The HUMAN enforcer can be configured within the JavaScript code via the `HumanSecurityConfiguration` object. ## HumanSecurityConfiguration An object of configuration values that dictate the behavior of the HumanSecurityEnforcer. This object is needed when initializing a new HumanSecurityEnforcer instance. Required values: * px\_app\_id * px\_auth\_token * px\_cookie\_secret > **Note** > > While you can add `PX_APP_ID`, `PX_COOKIE_SECRET`, and `PX_AUTH_TOKEN` directly, we recommend using Netlify environment variables so your configuration is more flexible and secure. See [Netlify's help documentation](https://docs.netlify.com/environment-variables/get-started/) for more information. ### px\_app\_id The application ID. Required to initialize the HumanSecurityEnforcer. ```ts const config: HumanSecurityConfiguration = { // ... px_app_id: '', // ... } ``` ### px\_auth\_token The token used for authorization with the HUMAN backend. Required to initialize the HumanSecurityEnforcer. ```ts const config: HumanSecurityConfiguration = { // ... px_auth_token: '', // ... } ``` ### px\_cookie\_secret The secret used to encrypt and decrypt the risk cookie. Required to initialize the HumanSecurityEnforcer. ```ts const config: HumanSecurityConfiguration = { // ... px_cookie_secret: '', // ... } ``` **Cookie secret rotation:** In case you would like to generate and use a new cookie secret, the enforcer will have to support both old and new cookie secrets to avoid multiple 'cookie decryption failed' errors. In your configuration, adjust the `px_cookie_secret` value to be an array of strings, that includes both the new cookie secret and the old cookie secret. The new cookie secret should be the first value in the new array. ```ts const config: HumanSecurityConfiguration = { // ... px_cookie_secret: ['', ''], // ... } ``` > **Note** > > The new cookie secret should be the first value in the new array. Array size is limited to 2 cookie secrets. ### px\_module\_enabled This boolean serves as an on/off switch for the entire module, providing a way to enable and disable all Enforcer capabilities quickly and easily. **Default**: `true` ```ts const config: HumanSecurityConfiguration = { // ... px_module_enabled: false, // ... } ``` ### px\_module\_mode This feature controls the behavior of the enforcer by changing how it executes certain parts of the workflow. Most notably, different modes allow for analysis and fine-tuning of the enforcer behavior without serving block pages that affect end users. Possible values: * `"monitor"` - the enforcer will perform all functions without returning block responses * `"active_blocking"` - the enforcer will return block responses when needed **Default**: `"monitor"` ```ts const config: HumanSecurityConfiguration = { // ... px_module_mode: 'active_blocking', // ... } ``` ### px\_logger\_severity The verbosity of the logs generated by the enforcer. Possible values: * `"none"` - No logs will be generated * `"error"` - Sparse logs will be generated only when errors occur * `"debug"` - Detailed logs will always be generated (not advisable for production environments) **Default**: `"error"` ```ts const config: HumanSecurityConfiguration = { // ... px_logger_severity: 'debug', // ... } ``` ### px\_s2s\_timeout The maximum time in milliseconds to wait for the risk API request. If this timeout is reached, the original request will be allowed to pass (fail open). **Default**: `1000` ```ts const config: HumanSecurityConfiguration = { // ... px_s2s_timeout: 2000, // ... } ``` ### px\_ip\_headers **Default**: `[]` ```ts const config: HumanSecurityConfiguration = { // ... px_ip_headers: ['true-ip', 'true-client-ip'], // ... } ``` ### px\_advanced\_blocking\_response\_enabled In specific cases (e.g., XHR post requests), a full captcha page render might not be an option. In such cases the advanced blocking response returns a JSON object containing all the information needed to render a customized captcha challenge implementation - be it a popup modal, a section on the page, etc. This allows for flexibility and customizability in terms\ of how the captcha pages are displayed. **Default**: `true` ```ts const config: HumanSecurityConfiguration = { // ... px_advanced_blocking_response_enabled: false, // ... } ``` ### px\_first\_party\_enabled To prevent suspicious or unwanted behavior on the client side, some browsers or extensions (e.g., adblockers) may deny the frontend JavaScript code from making requests to other domains. This prevents the HUMAN sensor from making requests to the HUMAN backends, which greatly limits HUMAN's detection capabilities. To avoid this problem, first party enables the enforcer to be used as a proxy for HUMAN servers, and to serve content to the browser from a first party endpoint (i.e., an endpoint on the customer’s domain). **Default**: `true` ```ts const config: HumanSecurityConfiguration = { // ... px_first_party_enabled: false, // ... } ``` ### px\_custom\_first\_party\_prefix By default, first party endpoints always begin with the application ID without the initial "PX". For example, if the application ID is `PX12345678`, then all first party routes will take the form `/12345678/*`. This configuration sets a custom prefix for first party routes to use in addition to the default prefix. When configured, the enforcer will respond to first party requests with endpoints matching the patterns `//init.js`, `//xhr/*`, and `//captcha/*`. **Default**: `""` (when empty, will use the default as described above) ```ts const config: HumanSecurityConfiguration = { // ... px_custom_first_party_prefix: "/custom-prefix", // ... } ``` ### px\_custom\_first\_party\_sensor\_endpoint For an application with ID `PX12345678`, the first party sensor endpoint is `/12345678/init.js` by default. This configuration customizes the entire first party sensor script endpoint. Note that in addition to responding to requests that match this configured route, the enforcer will also proxy first party requests that match the default pattern (`/12345678/init.js`) and patterns according to the custom prefix (`//init.js`) if one is configured. **Default**: `""` ```ts const config: HumanSecurityConfiguration = { // ... px_custom_first_party_sensor_endpoint: "/human_sensor", // ... } ``` ### px\_custom\_first\_party\_xhr\_endpoint For an application with ID `PX12345678`, the first party XHR endpoint is `/12345678/xhr` by default. This configuration customizes the first party XHR endpoint. Note that in addition to responding to requests that match this configured route, the enforcer will also proxy first party requests that match the default pattern (`/12345678/xhr/*`) and patterns according to the custom prefix (`//xhr/*`) if one is configured. **Default**: `""` ```ts const config: HumanSecurityConfiguration = { // ... px_custom_first_party_xhr_endpoint: "/human_xhr", // ... } ``` ### px\_custom\_first\_party\_captcha\_endpoint For an application with ID `PX12345678`, the first party captcha endpoint is `/12345678/captcha` by default. This configuration customizes the first party captcha endpoint. Note that in addition to responding to requests that match this configured route, the enforcer will also proxy first party requests that match the default pattern (`/12345678/captcha/*`) and patterns according to the custom prefix (`//captcha/*`) if one is configured. **Default**: `""` ```ts const config: HumanSecurityConfiguration = { // ... px_custom_first_party_captcha_endpoint: "/human_captcha", // ... } ``` ### px\_first\_party\_timeout\_ms The maximum time in milliseconds to wait for first party requests. **Default**: `4000` ```ts const config: HumanSecurityConfiguration = { // ... px_first_party_timeout_ms: 5000, // ... } ``` ### px\_bypass\_monitor\_header When enabling the enforcer for the first time, it is recommended to do so in monitor mode to collect data before actually starting to block user requests. Prior to switching the module mode to active\_blocking entirely, it's also crucial to verify that the full blocking flow works as expected. This feature activates the full blocking flow even while in monitor mode if a particular header is present on the request. **Default**: `"x-px-block"` ```ts const config: HumanSecurityConfiguration = { // ... px_bypass_monitor_header: 'human-block', // ... } ``` ### px\_enforced\_routes Customers may want certain, but not all, endpoints to be enforced by HUMAN, even when the Enforcer is in monitor mode. These routes will go through the full enforcer workflow, including blocking requests when necessary. That is, even when the enforcer is in monitor mode, these defined routes will behave as if in active blocking mode. **Default**: `[]` ```ts const config: HumanSecurityConfiguration = { // ... px_enforced_routes: ['/enforced_route', /.*\/enforced\/regex$/], // ... } ``` ### px\_custom\_is\_enforced\_request This configuration is meant for cases that require more complex custom logic. It is recommended to use the `px_enforced_routes` configuration for simpler cases. Customers may want certain, but not all, endpoints to be enforced by HUMAN, even when the Enforcer is in monitor mode. This configurable function provides a way to define which requests should be enforced based on custom logic. The function accepts the incoming request as an argument and returns a boolean indicating whether the request should be enforced (the request will behave as if in active blocking mode) or not. * Parameters * request: Request * Returns a boolean (or a Promise resolving to a boolean) **Default**: `null` ```ts const config: HumanSecurityConfiguration = { // ... px_custom_is_enforced_request: (request: Request): boolean | Promise => { return request.method === 'POST' && request.url.includes('/enforced_route'); }, // ... } ``` ### px\_monitored\_routes Enables certain endpoints to be monitored rather than enforced by HUMAN, even when the enforcer is in active blocking mode. **Default**: `[]` ```ts const config: HumanSecurityConfiguration = { // ... px_monitored_routes: ['/monitored_route', /.*\/monitored\/regex$/], // ... } ``` ### px\_custom\_is\_monitored\_request This configuration is meant for cases that require more complex custom logic. It is recommended to use the `px_monitored_routes` configuration for simpler cases. Customers may want certain, but not all, endpoints to be monitored by HUMAN, even when the Enforcer is in active\_blocking mode. This configurable function provides a way to define which requests should be monitored based on custom logic. The function accepts the incoming request as an argument and returns a boolean indicating whether the request should be monitored (the request will behave as if in monitor mode) or not. * Parameters * request: Request * Returns a boolean (or a Promise resolving to a boolean) **Default**: `null` ```ts const config: HumanSecurityConfiguration = { // ... px_custom_is_monitored_request: (request: Request): boolean | Promise => { return request.method === 'GET' && request.url.includes('/monitored'); }, // ... } ``` ### px\_sensitive\_headers The HUMAN detector requires information about the HTTP request as part of its bot detections. Certain headers may contain information that should not be forwarded to other servers, including the HUMAN backend. Configuring these header names as sensitive headers will remove these headers from requests sent to other backends by HUMAN. **Default**: `["cookie", "cookies"]` ```ts const config: HumanSecurityConfiguration = { // ... px_sensitive_headers: ['x-sensitive-token'], // ... } ``` ### px\_sensitive\_routes Certain endpoints may require more stringent protection from bot attacks (e.g., endpoints that execute payments or handle personal information). In these cases, routes can be configured as sensitive routes, meaning risk API calls will be made even if the request contains a valid, unexpired cookie. **Default**: `[]` ```ts const config: HumanSecurityConfiguration = { // ... px_sensitive_routes: ['/login', /.*\/sensitive\/regex$/], // ... } ``` ### px\_custom\_is\_sensitive\_request This configuration is meant for cases that require more complex custom logic. It is recommended to use the `px_sensitive_routes` configuration for simpler cases. Requests can be configured as sensitive, meaning risk API calls will be made even if the request contains a valid, unexpired cookie. This configurable function provides a way to define which requests should be considered sensitive based on custom logic. The function accepts the incoming request as an argument and returns a boolean indicating whether the request should be considered sensitive or not. * Parameters * request: Request * Returns a boolean (or a Promise resolving to a boolean) **Default**: `null` ```ts const config: HumanSecurityConfiguration = { // ... px_custom_is_sensitive_request: (request: Request): boolean | Promise => { return request.method === 'POST' || request.method === 'PUT'; }, // ... } ``` ### px\_filter\_by\_extension HUMAN does not enforce static assets such as images and documents. To prevent unnecessary API calls to HUMAN servers and needless computation, the enforcer filters all requests with a valid static file extension. Filtering by extension only applies to HTTP requests with methods GET and HEAD. **Default**: `[ '.css', '.bmp', '.tif', '.ttf', '.docx', '.woff2', '.js', '.pict', '.tiff', '.eot', '.xlsx', '.jpg', '.csv', '.eps', '.woff', '.xls', '.jpeg', '.doc', '.ejs', '.otf', '.pptx', '.gif', '.pdf', '.swf', '.svg', '.ps', '.ico', '.pls', '.midi', '.svgz', '.class', '.png', '.ppt', '.mid', '.webp', '.jar', '.json', '.xml' ]` ```ts const config: HumanSecurityConfiguration = { // ... px_filter_by_extension: ['.css', '.js', '.png'], // ... } ``` ### px\_filter\_by\_http\_method Filters out requests according to their HTTP method, avoiding unnecessary traffic in the enforcer verification flow and reducing operating costs. **Default**: `[]` ```ts const config: HumanSecurityConfiguration = { // ... px_filter_by_http_method: ['OPTIONS'], // ... } ``` ### px\_filter\_by\_ip Filters out requests according to their IP address, avoiding unnecessary traffic in the enforcer verification flow and reducing operation costs. **Default**: `[]` ```ts const config: HumanSecurityConfiguration = { // ... px_filter_by_ip: ['1.1.1.1', '2.2.2.2/8'], // ... } ``` ### px\_filter\_by\_route Route prefixes (endpoints) specified here will not be blocked, regardless of the score they receive. A request to a filtered route will not generate any risk or async activities. **Default**: `[]` ```ts const config: HumanSecurityConfiguration = { // ... px_filter_by_route: ['/filtered_route', /.*\/filtered\/regex$/], // ... } ``` ### px\_filter\_by\_user\_agent Filters out requests according to their user agent value, avoiding unnecessary traffic in the enforcer verification flow and reducing operation costs. **Default**: `[]` ```ts const config: HumanSecurityConfiguration = { // ... px_filter_by_user_agent: ['filtered_UA'], // ... } ``` ### px\_custom\_is\_filtered\_request This configuration is meant for cases that require more complex custom logic. It is recommended to use the `px_filter_by_route`, `px_filter_by_user_agent`, `px_filter_by_http_method`, `px_filter_by_ip`, and `px_filter_by_extension` configurations for simpler cases. Customers may prefer to filter certain requests (i.e., not apply HUMAN enforcement at all). These requests will not be blocked, and they will not generate any risk or async activities. This configurable function provides a way to define which requests should be filtered based on custom logic. The function accepts the incoming request as an argument and returns a boolean indicating whether the request should be filtered or not. * Parameters * request: Request * Returns a boolean (or a Promise resolving to a boolean) **Default**: `null` ```ts const config: HumanSecurityConfiguration = { // ... px_custom_is_filtered_request: (request: Request): boolean | Promise => { return request.method === 'GET' && request.url.includes('/static/'); }, // ... } ``` ### px\_css\_ref Provides a way to include an additional custom .css file to add to the block page. **Default**: `""` ```ts const config: HumanSecurityConfiguration = { // ... px_css_ref: 'https://www.example.com/custom_style.css', // ... } ``` ### px\_js\_ref Provides a way to include a custom JS script to add to the block page. This script will run after the default JS scripts. **Default**: `""` ```ts const config: HumanSecurityConfiguration = { // ... px_js_ref: 'https://www.example.com/custom_script.js', // ... } ``` ### px\_custom\_logo Adds a custom logo to the block page that will be shown to users. This aligns the block page with the customer's brand. **Default**: `""` ```ts const config: HumanSecurityConfiguration = { // ... px_custom_logo: 'https://www.example.com/custom_logo.png', // ... } ``` ### px\_custom\_cookie\_header The Enforcer attempts to extract the HUMAN cookies from the 'Cookie' header. If the HUMAN cookies are transferred on a header other than 'Cookie', the header name should be configured here. **Default**: `""` ```ts const config: HumanSecurityConfiguration = { // ... px_custom_cookie_header: 'x-px-cookies', // ... } ``` ### px\_user\_agent\_max\_length The maximum length of the `User-Agent` header. If the user agent header value exceeds this length, it will be truncated to this length prior to processing. **Default**: `8528` ```ts const config: HumanSecurityConfiguration = { // ... px_user_agent_max_length: 2048, // ... } ``` This value should not be changed without consulting with the HUMAN Customer Success team. ### px\_secured\_pxhd\_enabled Whether the PXHD cookie set on the HTTP response should include the [Secure attribute](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#restrict_access_to_cookies). **Default**: `false` ```ts const config: HumanSecurityConfiguration = { // ... px_secured_pxhd_enabled: true, // ... } ``` ### px\_cors\_support\_enabled CORS (Cross-Origin Resource Sharing) is a mechanism that enables the server to indicate when a request contains cross-origin resources. It does so by adding special HTTP headers to the request, which permits the browser to load these resources. Without these headers, the browser may block requests to these resources for security reasons. In most cases, CORS employs a two-stage procedure with a preliminary "preflight" request followed by the actual request. The preflight request checks if the actual request will be responded to. To learn more about different request types, see these [examples](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#examples_of_access_control_scenarios). In the Enforcer, CORS behavior must be configured to address both simple requests (without preflight) and more complex ones (with preflight). Enabling CORS support via this configuration will have the following effects: * It will automatically add the following default CORS response headers to block responses resulting from CORS requests. ```none Access-Control-Allow-Origin: Access-Control-Allow-Credentials: true ``` * It will activate the `px_cors_create_custom_block_response_headers` configuration, which will allow for customizing the block response headers via a custom function. * It will activate the `px_cors_preflight_request_filter_enabled` and `px_cors_custom_preflight_handler` configurations, which allow for filtering and custom handling of preflight requests. **Default**: `false` ```ts const config: HumanSecurityConfiguration = { // ... px_cors_support_enabled: true, // ... } ``` ### px\_cors\_create\_custom\_block\_response\_headers If the default CORS response headers are not sufficient, this configuration can be used to completely customize the headers that should be added to all block responses resulting from CORS requests. If this function is defined, the default headers will *not* be added; only those headers specified in the returned object will be added to the block response. * Parameters * request: Request * Returns an object of the type Record\ (or a Promise resolving to this type) **Default:** `null` ```ts const config: HumanSecurityConfiguration = { // ... px_cors_create_custom_block_response_headers: ( request: Request, ): Record => { return { 'Access-Control-Allow-Origin': [request.headers.get('origin')], 'Access-Control-Allow-Credentials': ['false'], 'Access-Control-Allow-Methods': ['GET', 'POST', 'PUT'], 'X-Custom-Header': ['1'] }; }, // ... } ``` > **Note** > > The request body cannot be read more than once! If you plan on reading the request body in this function, it is recommended to clone the request prior to doing so. ### px\_cors\_preflight\_request\_filter\_enabled This configuration disables enforcement for CORS preflight requests. When this configuration is set to true, CORS preflight requests will be filtered from the enforcer flow. That is, they will pass through the enforcer flow without triggering detection or block responses. **Default**: `false` ```ts const config: HumanSecurityConfiguration = { // ... px_cors_preflight_request_filter_enabled: true, // ... } ``` ### px\_cors\_custom\_preflight\_handler If a more customized approach is needed for handling CORS preflight requests, this custom function can be set to define the desired behavior. The custom function should receive the original HTTP request and return an object representing the HTTP response to be returned. If `null` or any other falsy value is returned from the function, the Enforcer will continue processing the preflight request. Custom Preflight Handler and Preflight Request Filtering The `px_cors_custom_preflight_handler` will be invoked prior to determining whether or not to filter the request based on the `px_cors_preflight_request_filter_enabled` configuration. This allows for returning customized responses for preflight requests that meet certain conditions and filtering those that don't meet these conditions. * Parameters * request: Request * Returns either null or an object implementing the IMinimalResponse interface (defined below). It is also possible to return a Promise resolving to one of these types. ```ts interface IMinimalResponse { status: number; headers: Record; body: any; }; ``` **Default**: `null` ```ts const config: HumanSecurityConfiguration = { // ... px_cors_custom_preflight_handler: (request: Request): `IMinimalResponse` | `Promise<`IMinimalResponse`>` => { const headers = { 'Access-Control-Allow-Origin': [request.headers.get('origin')], 'Access-Control-Allow-Methods': [request.headers.get('access-control-request-method')], 'Access-Control-Allow-Headers': [request.headers.get('access-control-request-headers')], 'Access-Control-Allow-Credentials': ['true'], 'Access-Control-Max-Age': ['86400'] }; return { status: 204, headers, body: null, }; }, // ... } ``` > **Note** > > The request body cannot be read more than once! If you plan on reading the request body in this function, it is recommended to clone the request prior to doing so. ### px\_additional\_activity\_handler The additional activity handler is a custom function passed to the enforcer. The enforcer runs this callback after sending `page_requested` or `block` activity to the collector, and before forwarding the request to the next step in the pipeline. A common use case of the additional activity handler is to set the score as a variable or header. Then the application can read the score and do what is defined within the application's logic. * Parameters * config: HumanSecurityConfiguration * context: IContext * request: Request * Returns void or a Promise resolving to void **Default**: `null` ```ts const config: HumanSecurityConfiguration = { // ... px_additional_activity_handler: ( config: HumanSecurityConfiguration, context: IContext, request: Request ): void => { request.headers.set('x-px-score', `${context.score}`); request.headers.set('x-px-rtt', `${context.riskApiData.riskRtt}`); }, // ... } ``` > **Note** > > The request body cannot be read more than once! If you plan on reading the request body in this function, it is recommended to clone the request prior to doing so. ### px\_enrich\_custom\_parameters This custom function enriches activities sent from the enforcer to HUMAN with additional custom data. This data can include user information, session IDs, or other data that HUMAN should have access to. These custom parameters are defined by a configurable function that must return an object that contains these custom parameters. There is a limit of 10 custom parameters. * Parameters * config: HumanSecurityConfiguration * request: Request * Returns `CustomParameters` | `Promise<`CustomParameters`>` **Default**: null ```ts const config: HumanSecurityConfiguration = { // ... px_enrich_custom_parameters: async ( config: HumanSecurityConfiguration, request: Request, ): `CustomParameters` | `Promise<`CustomParameters`>` => { const body = request.method === 'POST' && request.headers.get('content-type')?.includes('application/json') ? await request.clone().json() : null; return { custom_param1: 'hardcoded value', custom_param2: request.headers.get('header-name'), custom_param3: body?.['body_property'] }; }, // ... } ``` > **Note** > > The request body cannot be read more than once! If you plan on reading the request body in this function, it is recommended to clone the request prior to doing so. ### px\_graphql\_enabled Whether the enforcer should attempt to parse and report information about GraphQL operations on incoming requests. **Default**: `true` ```ts const config: HumanSecurityConfiguration = { // ... px_graphql_enabled: false, // ... } ``` ### px\_graphql\_routes A list of prefixes for all routes that should be considered GraphQL routes. If `px_graphql_enabled` is `true`, all POST requests with routes that match the prefixes configured here will have their bodies parsed for GraphQL operations. **Default**: `["/graphql"]` ```ts const config: HumanSecurityConfiguration = { // ... px_graphql_routes: ['/graphql', /^\/\w+\/graphql/], // ... } ``` ### px\_sensitive\_graphql\_operation\_types A list of operation types (query, mutation, or subscription) that should be considered sensitive. If one or more GraphQL operations on an HTTP request is found to have a type matching the list configured here, it will trigger a Risk API call even if the request contains a valid, unexpired cookie. **Default**: `[]` ```ts const config: HumanSecurityConfiguration = { // ... px_sensitive_graphql_operation_types: ['mutation'], // ... } ``` ### px\_sensitive\_graphql\_operation\_names As of version 6.3.0, this configuration supports regular expressions and matches against any extracted GraphQL keywords. For more information, see the `px_graphql_keywords` and `px_extract_graphql_keywords` configurations. A list of operation names or keywords that should be considered sensitive if found in the query. Either a string or regular expression can be configured. If any GraphQL operation is found to have an operation name or extracted keyword that matches one of the configured items, the HTTP request will trigger a Risk API call even if it contains a valid, unexpired cookie. **Default**: `[]` ```ts const config: HumanSecurityConfiguration = { // ... px_sensitive_graphql_operation_names: ['LoginOperation', /sensitiveKeyword/], // ... } ``` ### px\_graphql\_keywords This configuration was added in version 6.3.0. A list of strings and/or regular expressions used to identify important terms from the GraphQL operation queries. All strings in a GraphQL query matching the patterns configured here will be extracted and reported to HUMAN. These keywords are used to determine the purpose of the operation (e.g., login, checkout, search), and can also be used to specify which GraphQL operations should be considered sensitive. See the `px_sensitive_graphql_operation_names` configuration for more information. **Default**: `[]` ```ts const config: HumanSecurityConfiguration = { // ... px_graphql_keywords: ['performLogin', 'addToCart', /keyword\d+/], // ... } ``` ### px\_extract\_graphql\_keywords This configuration was added in version 6.3.0. A custom function for identifying key terms from GraphQL operation queries, providing an alternative to the `px_graphql_keywords` configuration. If a list of strings and/or regular expressions is insufficient to GraphQL keywords, this custom function offers more flexibility. The function accepts the GraphQL query string and must return an array of strings representing all keywords found in the query. These keywords are used to determine the purpose of the operation (e.g., login, checkout, search), and can also be used to specify which GraphQL operations should be considered sensitive. See the `px_sensitive_graphql_operation_names` configuration for more information. If this function is defined and returns an array (even an empty array), then the returned array will be used as the GraphQL keywords. If this function is defined and returns `null`, then the query will continue to be evaluated using `px_graphql_keywords`. * Parameters * graphqlQuery: string * Returns string\[] | Promise\ **Default**: `null` ```ts const config: HumanSecurityConfiguration = { // ... px_extract_graphql_keywords: (graphqlQuery: string): string[] | Promise => { if (/userId\d+/.test(graphqlQuery)) { // report no keywords for this query return []; } else if (/perform(Login|Signin)/.test(graphqlQuery)) { // always report 'login' as the only keyword for this query return ['login']; } else { // process query according to px_graphql_keywords configuration return null; } }, // ... } ``` ### px\_score\_header\_name When set, this will add a header to the incoming request with the configured header name and the score (0-100) as the value. If empty, no header will be set. **Default**: `""` ```ts const config: HumanSecurityConfiguration = { // ... px_score_header_name: 'x-human-score', // ... } ``` ### px\_client\_uuid\_header\_name When set, this will add a header to the incoming request with the configured header name and the client UUID as the value. If empty, no header will be set. **Default**: `""` ```ts const config: HumanSecurityConfiguration = { // ... px_client_uuid_header_name: 'x-human-uuid', // ... } ``` ## Account Defender Configurations ### px\_jwt\_cookie\_name The name of the cookie that contains the JWT token from which user identifiers should be extracted. **Default**: `""` ```ts const config: HumanSecurityConfiguration = { // ... px_jwt_cookie_name: 'auth', // ... } ``` ### px\_jwt\_cookie\_user\_id\_field\_name The field name in the JWT object, extracted from the JWT cookie, that contains the user ID to be extracted and reported. **Default**: `""` ```ts const config: HumanSecurityConfiguration = { // ... px_jwt_cookie_user_id_field_name: 'nameID', // ... } ``` ### px\_jwt\_cookie\_additional\_field\_names The field names in the JWT object, extracted from the JWT cookie, that should be extracted and reported in addition to the user ID. **Default**: `[]` ```ts const config: HumanSecurityConfiguration = { // ... px_jwt_cookie_additional_field_names: ['exp', 'iss'], // ... } ``` ### px\_jwt\_header\_name The name of the header that contains the JWT token from which user identifiers should be extracted. **Default**: `""` ```ts const config: HumanSecurityConfiguration = { // ... px_jwt_header_name: 'x-jwt-authorization', // ... } ``` ### px\_jwt\_header\_user\_id\_field\_name The field name in the JWT object, extracted from the JWT header, that contains the user ID to be extracted and reported. **Default**: `""` ```ts const config: HumanSecurityConfiguration = { // ... px_jwt_header_user_id_field_name: 'sub', // ... } ``` ### px\_jwt\_header\_additional\_field\_names The field names in the JWT object, extracted from the JWT header, that should be extracted and reported in addition to the user ID. **Default**: `[]` ```ts const config: HumanSecurityConfiguration = { // ... px_jwt_header_additional_field_names: ['exp', 'iss'], // ... } ``` ## Hype Sale Challenge The enforcer will serve a Hype Sale Challenge for any request that is marked as a hype sale. To mark a request as hype sale, add a custom parameter with the key `is_hype_sale` and a boolean value of `true` in the [configurable custom parameters function](#px_enrich_custom_parameters). The following configuration will initiate a Hype Sale Challenge for any request that contains the query param `id` with the value `123` (e.g., `https://www.example.com/product?id=123`). ```ts const config: HumanSecurityConfiguration = { // ... px_enrich_custom_parameters: async ( config: HumanSecurityConfiguration, request: Request, ): `CustomParameters` | `Promise<`CustomParameters`>` => { const { searchParams } = new URL(request.url); return { is_hype_sale: searchParams.has('id') && searchParams.get('id') === '123' }; }, // ... } ``` ## Remote Configurations ### px\_logger\_auth\_token The token used to authenticate with HUMAN's enforcer logging services. This value is required for setting up the header-based logger feature as well as configuring the enforcer from the HUMAN Portal. **Default**: `""` ```ts const config: HumanSecurityConfiguration = { // ... px_logger_auth_token: '', // ... } ``` ### px\_remote\_config\_secret Removed This configuration value has been removed as of v6.2.0. The secret value for verifying remote configuration push requests, which update the enforcer configuration. This value is required for configuring the enforcer from the HUMAN Portal. **Default**: `""` ```ts const config: HumanSecurityConfiguration = { // ... px_remote_config_secret: '', // ... } ``` ### px\_remote\_config\_auth\_token The token used to authenticate the enforcer with the HUMAN remote configuration service. This value is required for configuring the enforcer from the HUMAN Portal. **Default**: `""` ```ts const config: HumanSecurityConfiguration = { // ... px_remote_config_auth_token: '', // ... } ``` ### px\_remote\_config\_kv\_key\_name When using the PXKV namespace for remote configurations, this static configuration will determine the KV key name whose value will contain the enforcer configuration. **Default**: `"ENFORCER_CONFIG"` ```ts const config: HumanSecurityConfiguration = { // ... px_remote_config_kv_key_name: 'human_config', // ... } ```