Merge pull request #153 from PerimeterX/dev

Version 5.1.0

Author: Yaron Schwimmer

CHANGELOG.md

@@ -5,6 +5,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
+## [5.1.0] - 2018-09-26
+### Added
+- Support for Advanced Blocking Response
+
+### Fixed
+- Updated http/2 documentation section
+- firstPartyEnabled property for Captcha
+
 ## [5.0.1] - 2018-09-02
 ### Added
 - Refreshed documentation

README.md

@@ -4,7 +4,7 @@
 
 # [PerimeterX](http://www.perimeterx.com) NGINX Lua Plugin
 
-> Latest stable version: [v5.0.1](https://luarocks.org/modules/bendpx/perimeterx-nginx-plugin/5.0-1)
+> Latest stable version: [v5.1.0](https://luarocks.org/modules/bendpx/perimeterx-nginx-plugin/5.1-0)
 
 
 ## [Introduction](#introduction)
@@ -50,7 +50,9 @@
 ## [Enrichment](#enrichment)
  * [Data Enrichment](#data-enrichment)
  * [Log Enrichment](#log-enrichment)
-  
+
+## [Advanced Blocking Response](#advancedBlockingResponse)
+
 ## [Appendix](#appendix)  
  * [HTTP v2 Support](#http2)
  * [NGINX Plus](#nginxplus)
@@ -555,6 +557,8 @@ The following configurations are set in:
   }
   ```
 
+> NOTE: If your NGINX version supports HTTP v2, refer to the [HTTP v2 section of the Appendix](#http2).
+
 > NOTE: The PerimeterX NGINX Lua Plugin Configuration Requirements must be completed before proceeding to the next stage of installation.
 
 ##### <a name="perimterx_first_party_js_snippet"></a> First-Party JS Snippet
@@ -863,8 +867,41 @@ For more information and the available fields in the JSON, refer to the Perimete
     }
     ...
   ```
+
+<a name="advancedBlockingResponse"></a> Advanced Blocking Response
+------------------------------------------------------------------
+In special cases, (such as XHR post requests) a full Captcha page render might not be an option. In such cases, using the Advanced Blocking Response returns a JSON object continaing all the information needed to render your own Captcha challenge implementation, be it a popup modal, a section on the page, etc. The Advanced Blocking Response occurs when a request contains the *Accept* header with the value of `application/json`. A sample JSON response appears as follows:
+
+```javascript
+{
+    "appId": String,
+    "jsClientSrc": String,
+    "firstPartyEnabled": Boolean,
+    "vid": String,
+    "uuid": String,
+    "hostUrl": String,
+    "blockScript": String
+}
+```
+
+Once you have the JSON response object, you can pass it to your implementation (with query strings or any other solution) and render the Captcha challenge.
+
+In addition, you can add the `_pxOnCaptchaSuccess` callback function on the window object of your Captcha page to react according to the Captcha status. For example when using a modal, you can use this callback to close the modal once the Captcha is successfullt solved. <br/> An example of using the `_pxOnCaptchaSuccess` callback is as follows:
+
+```javascript
+window._pxOnCaptchaSuccess = function(isValid) {
+    if(isValid) {
+        alert("yay");
+    } else {
+        alert("nay");
+    }
+}
+```
+
+For details on how to create a custom Captcha page, refer to the [documentation](https://console.perimeterx.com/docs/server_integration_new.html#custom-captcha-section)
+
 <a name="appendix"></a> Appendix
------------------------------------------------
+--------------------------------
 
 ### <a name="http2"></a> HTTP v2 Support
   The PerimeterX NGINX module supports HTTP v2 for both Third-Party and First-Party implementations. To verify that your NGINX is running with HTTP v2 support, run:

lib/px/block/pxblock.lua

@@ -23,6 +23,15 @@ function M.load(px_config)
     local ngx_exit = ngx.exit
     local string_gsub = string.gsub
 
+    local function is_accept_header_json(header)
+        for h in string.gmatch(header, '[^,]+') do
+            if string.lower(h) == "application/json" then
+                return true;
+            end
+        end
+        return false
+    end
+
     local function inject_captcha_script(vid, uuid)
         return '<script type="text/javascript">window._pxVid = "' .. vid .. '";' ..
                 'window._pxUuid = "' .. uuid .. '";</script>'
@@ -104,6 +113,26 @@ function M.load(px_config)
             return
         end
 
+        -- json response
+        local accept_header = ngx.req.get_headers()["accept"] or ngx.req.get_headers()["content-type"]
+        local isJsonResponse = accept_header and is_accept_header_json(accept_header) and not ngx.ctx.px_is_mobile
+        if isJsonResponse then
+            local props = px_template.get_props(px_config, details.block_uuid, vid, parse_action(ngx.ctx.px_action))
+            local result = {
+                appId = props.appId,
+                jsClientSrc = props.jsClientSrc,
+                firstPartyEnabled = props.firstPartyEnabled,
+                vid = props.firstPartyEnabled,
+                uuid = props.uuid,
+                hostUrl = props.hostUrl,
+                blockScript = props.blockScript
+            }
+            ngx.header["Content-Type"] = 'application/json';
+            ngx.status = ngx_HTTP_FORBIDDEN;
+            ngx.say(cjson.encode(result))
+            ngx_exit(ngx.OK)
+        end
+
         -- web scenarios
         ngx.header["Content-Type"] = 'text/html';
 

lib/px/block/pxtemplate.lua

@@ -11,22 +11,23 @@ function M.load(px_config)
     local px_constants = require "px.utils.pxconstants"
     local px_logger = require("px.utils.pxlogger").load(px_config)
 
-    local function get_props(px_config, uuid, vid, action)
+    function _M.get_props(px_config, uuid, vid, action)
         local logo_css_style = 'visible'
         if (px_config.custom_logo == nil) then
             logo_css_style = 'hidden'
         end
 
-        local is_mobile = ngx.ctx.px_cookie_origin == 'header'
         local js_client_src = string.format('//client.perimeterx.net/%s/main.min.js', px_config.px_appId)
         local collectorUrl = '//' .. px_config.collector_host
-        local captcha_url_prefix = 'https://' .. px_config.captcha_script_host
+        local captcha_url_prefix = '//' .. px_config.captcha_script_host
+        local first_party_enabled = false
         -- in case we are in first party mode (not relevant for mobile), change the base paths to use first party
-        if px_config.first_party_enabled and not is_mobile then
+        if px_config.first_party_enabled and not ngx.ctx.px_is_mobile then
             local reverse_prefix = string.sub(px_config.px_appId, 3, string.len(px_config.px_appId))
             js_client_src = string.format('/%s%s', reverse_prefix, px_constants.FIRST_PARTY_VENDOR_PATH)
             collectorUrl = string.format('/%s%s', reverse_prefix, px_constants.FIRST_PARTY_XHR_PATH)
             captcha_url_prefix = string.format('/%s%s', reverse_prefix, px_constants.FIRST_PARTY_CAPTCHA_PATH)
+            first_party_enabled = true
         end
         local captcha_src = ''
         if action ~= 'r' then
@@ -44,7 +45,7 @@ function M.load(px_config)
             logoVisibility = logo_css_style,
             hostUrl = collectorUrl,
             jsClientSrc = js_client_src,
-            firstPartyEnabled = px_config.first_party_enabled,
+            firstPartyEnabled = first_party_enabled,
             blockScript = captcha_src
         }
     end
@@ -72,7 +73,7 @@ function M.load(px_config)
     end
 
     function _M.get_template(action, uuid, vid)
-        local props = get_props(px_config, uuid, vid, action)
+        local props = _M.get_props(px_config, uuid, vid, action)
         local templateStr = get_content(action)
 
         return lustache:render(templateStr, props)

lib/px/utils/pxconstants.lua

@@ -3,7 +3,7 @@
 ----------------------------------------------
 
 local _M = {
-    MODULE_VERSION = "NGINX Module v5.0.1",
+    MODULE_VERSION = "NGINX Module v5.1.0",
     RISK_PATH = "/api/v3/risk",
     CAPTCHA_PATH = "/api/v2/risk/captcha",
     ACTIVITIES_PATH = "/api/v1/collector/s2s",

lib/px/utils/pxpayload.lua

@@ -40,6 +40,7 @@ end
 
 function PXPayload:get_payload()
     ngx.ctx.px_cookie_origin = "cookie"
+    ngx.ctx.px_is_mobile = false;
     local px_header = self.px_headers.get_header('X-PX-AUTHORIZATION')
 
     if (px_header) then
@@ -48,6 +49,8 @@ function PXPayload:get_payload()
         ngx.ctx.px_orig_cookie = cookie
         ngx.ctx.px_header = px_header
         ngx.ctx.px_cookie_origin = "header"
+        ngx.ctx.px_is_mobile = true;
+
         if version == "3" then
             ngx.ctx.px_cookie_version = "v3";
             self.px_logger.debug("Token V3 found - Evaluating")

perimeterx-nginx-plugin-5.0-1.rockspec perimeterx-nginx-plugin-5.1-0.rockspecperimeterx-nginx-plugin-5.0-1.rockspec renamed to perimeterx-nginx-plugin-5.1-0.rockspec

@@ -1,8 +1,8 @@
  package = "perimeterx-nginx-plugin"
- version = "5.0-1"
+ version = "5.1-0"
  source = {
     url = "git://github.com/PerimeterX/perimeterx-nginx-plugin.git",
-    tag = "v5.0.1",
+    tag = "v5.1.0",
  }
  description = {
     summary = "PerimeterX NGINX Lua Middleware.",