Merge a0ee87984df18b1c59d4114df0246339f5af8187 into da6852df4103492f9136ef814cda0c7d402e0a90

.github/workflows/nginx-module-build.yml

@@ -0,0 +1,52 @@
+name: Build NGINX Module
+
+on:
+  push:
+    branches:
+      - master  # Ensure this matches your main branch name
+  pull_request:
+    branches:
+      - master
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v3
+
+    - name: Install dependencies
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y nginx gcc make
+
+    - name: Download and extract NGINX source
+      run: |
+        wget https://nginx.org/download/nginx-1.25.4.tar.gz
+        tar -xvzf nginx-1.25.4.tar.gz
+        echo "NGINX_PATH=$(pwd)/nginx-1.25.4" >> $GITHUB_ENV
+
+    - name: Run build script
+      run: |
+        chmod +x build.sh
+        ./build.sh
+
+    - name: List modules
+      run: |
+        ls ${NGINX_PATH}/objs
+
+    - name: Package module
+      run: |
+        find ${NGINX_PATH}/objs -name "*.so" -exec tar -czvf ngx_http_js_challenge_module.tar.gz -C ${NGINX_PATH}/objs {} +
+
+    - name: Upload Artifact
+      uses: actions/upload-artifact@v3
+      with:
+        name: ngx_http_js_challenge_module
+        path: ngx_http_js_challenge_module.tar.gz
+
+    - name: Check module output
+      run: |
+        ls ${NGINX_PATH}/objs/*.so
+

README.md

@@ -1,40 +1,64 @@
+# ngx_http_js_challenge_module
 
-## ngx_http_js_challenge_module
+[![GitHub License](https://img.shields.io/github/license/simon987/ngx_http_js_challenge_module.svg)](LICENSE)
-
-![GitHub](https://img.shields.io/github/license/simon987/ngx_http_js_challenge_module.svg)
 [![CodeFactor](https://www.codefactor.io/repository/github/simon987/ngx_http_js_challenge_module/badge)](https://www.codefactor.io/repository/github/simon987/ngx_http_js_challenge_module)
+[![Demo Website](https://img.shields.io/badge/demo-website-blue.svg)](https://ngx-js-demo.simon987.net/)
 
+Simple JavaScript proof-of-work based access control for Nginx, designed to provide security with minimal overhead.
 
-[Demo website](https://ngx-js-demo.simon987.net/)
+## Features
 
-Simple javascript proof-of-work based access for Nginx with virtually no overhead.
+- **Lightweight Integration:** Easy to integrate with existing Nginx installations.
+- **Configurable Security:** Flexible settings to adjust security strength and client experience.
+- **Minimal Performance Impact:** Designed to operate with virtually no additional server load.
 
-Easy installation: just add `load_module /path/to/ngx_http_js_challenge_module.so;` to your
+## Quick Start
-`nginx.conf` file and follow the [configuration instructions](#configuration).
 
-<p align="center">
+1. **Installation**
-  <img width="600px" src="throughput.png"/>
+   Add the following line to your `nginx.conf`:
-</p>
+   ```
+   load_module /path/to/ngx_http_js_challenge_module.so;
+   ```
 
-### Configuration
+2. **Configuration**
+   Use the simple or advanced configurations provided below to customize the module to your needs.
 
-**Simple configuration**
+## Installation
-```nginx
+
+To install the ngx_http_js_challenge_module, follow these steps:
+
+1. Add the module loading directive to your Nginx configuration file (`/etc/nginx/nginx.conf`):
+   ```
+   load_module /path/to/ngx_http_js_challenge_module.so;
+   ```
+
+2. Apply the changes by reloading Nginx:
+   ```
+   nginx -s reload
+   ```
+
+## Configuration
+
+### Basic Configuration
+
+For basic setup, update your server block as follows:
+
+```
 server {
     js_challenge on;
-    js_challenge_secret "change me!";
+    js_challenge_secret "change me!";  # Ensure to replace this with a strong secret in production
-
-    # ...
 }
 ```
 
+### Advanced Configuration
 
-**Advanced configuration**
+For more complex setups, including exemptions for specific paths:
-```nginx
+
+```
 server {
     js_challenge on;
     js_challenge_secret "change me!";
-    js_challenge_html /path/to/body.html;
+    js_challenge_html "/path/to/body.html";
     js_challenge_bucket_duration 3600;
     js_challenge_title "Verifying your browser...";
 
@@ -45,49 +69,51 @@ server {
 
     location /sensitive {
         js_challenge_bucket_duration 600;
-        #...
+        # Add further customization here
     }
-
-    #...
 }
 ```
 
-* `js_challenge on|off` Toggle javascript challenges for this config block
+### Parameters
-* `js_challenge_secret "secret"` Secret for generating the challenges. DEFAULT: "changeme"
+
-* `js_challenge_html "/path/to/file.html"` Path to html file to be inserted in the `<body>` tag of the interstitial page
+- **js_challenge on|off** Toggle javascript challenges for this config block
-* `js_challenge_title "title"` Will be inserted in the `<title>` tag of the interstitial page. DEFAULT: "Verifying your browser..."
+- **js_challenge_secret "secret"** Secret for generating the challenges. DEFAULT: "changeme"
-* `js_challenge_bucket_duration time` Interval to prompt js challenge, in seconds. DEFAULT: 3600
+- **js_challenge_html "/path/to/file.html"** Path to html file to be inserted in the `<body>` tag of the interstitial page
+- **js_challenge_title "title"** Will be inserted in the `<title>` tag of the interstitial page. DEFAULT: "Verifying your browser..."
+- **js_challenge_bucket_duration time** Interval to prompt js challenge, in seconds. DEFAULT: 3600
 
 ### Installation
 
 1. Add `load_module ngx_http_js_challenge_module.so;` to `/etc/nginx/nginx.conf`
-1. Reload `nginx -s reload`
+2. Reload `nginx -s reload`
 
 ### Build from source
 
 These steps have to be performed on machine with compatible configuration (same nginx, glibc, openssl version etc.)
 
 1. Install dependencies
-    ```bash
+    ```
     apt install libperl-dev libgeoip-dev libgd-dev libxslt1-dev libpcre3-dev
     ```
 2. Download nginx tarball corresponding to your current version (Check with `nginx -v`)
-    ```bash
+    ```
-   wget https://nginx.org/download/nginx-1.16.1.tar.gz
+    wget https://nginx.org/download/nginx-1.25.4.tar.gz
-   tar -xzf nginx-1.16.1.tar.gz
+    tar -xzf nginx-1.25.4.tar.gz
-   export NGINX_PATH=$(pwd)/nginx-1.16.1/
+    export NGINX_PATH=$(pwd)/nginx-1.25.4/
     ```
 3. Compile the module
-    ```bash
+    ```
     git clone https://github.com/simon987/ngx_http_js_challenge_module
     cd ngx_http_js_challenge_module
     ./build.sh
     ```
 4. The dynamic module can be found at `${NGINX_PATH}/objs/ngx_http_js_challenge_module.so`
 
+### Known limitations (To Do)
 
+* None
 
-### Known limitations / TODO
+### Throughput
-
+<p align="center">
-* Users with cookies disabled will be stuck in an infinite refresh loop (TODO: redirect with a known query param, if no cookie is specified but the query arg is set, display an error page)
+  <img width="600px" src="throughput.png"/>
-* If nginx is behind a reverse proxy/load balancer, the same challenge will be sent to different users and/or the response cookie will be invalidated when the user is re-routed to another server. (TODO: use the x-real-ip header when available) 
+</p>