feat: Add lws_captcha_ratelimit plugin and core integration

Co-developed-by: Gemini 3.0 Pro

Author: lws-team

READMEs/README-captcha.md

@@ -0,0 +1,91 @@
+# lws_captcha_ratelimit plugin
+
+This plugin provides a simple interceptor mechanism based on a time delay (rate limit). It is designed to be used with the LWS `interceptor_path` mount option.
+
+## Functionality
+
+When a user accesses a protected mount, LWS checks for a valid JWT cookie. If the cookie is missing or invalid, the request is diverted to the `interceptor_path`. This plugin, when mounted at `interceptor_path`, serves a simple HTML page with a button.
+
+Both before, and after when the user clicks the button, the plugin enforces a configurable wait. After the wait, it issues a signed JWT cookie valid for a configured duration (default 10 minutes) and redirects the user back to the original URL.
+
+## Configuration
+
+### 1. Enable the Plugin
+
+Ensure `protocol_lws_captcha_ratelimit` is enabled in your build.
+
+### 2. Configure Vhost PVOs
+
+The plugin is configured via per-vhost options (PVOs) under the protocol name `lws_captcha_ratelimit`.
+
+| Option | Description | Default |
+|---|---|---|
+| `jwt-issuer` | The issuer claim (`iss`) for the JWT. | "lws" |
+| `jwt-audience` | The audience claim (`aud`) for the JWT. | "lws" |
+| `jwt-alg` | The signing algorithm. | "HS256" |
+| `jwt-expiry` | Validity duration of the JWT in seconds. | 600 (10 mins) |
+| `cookie-name` | The name of the cookie to set/check. | "lws_captcha_ratelimit" |
+| `jwt-jwk` | **Required.** Path to a file containing the JWK (JSON Web Key) or the JWK JSON itself. | - |
+| `asset-dir` | Path to interceptor assets (CSS, JS, images). Use `file://` prefix for local paths. | - |
+| `pre-delay-ms` | Delay before "Continue" button appears. | 5000 |
+| `post-delay-ms` | Delay after "Continue" button is pressed. | 3000 |
+| `status` | Status message to display. | "ok" |
+| `stats-logging` | Whether to emit once-a-minute status logging | 0 |
+
+**JWK Generation:**
+
+The JWK can be produced by `lws-crypto-jwk -t OCT`.
+
+**Example JWK (`captcha-key.jwk`):**
+```json
+{"kty":"oct","k":"AyM1SysPpbyDfgZld3umj1qzKObwVMkoqQ-EstJQLr_T-1qS0gZH75aKtMN3Yj0iPS4hcgUuTwjAzZr1Z9CAow"}
+```
+
+### 3. Configure Mounts
+
+In your JSON configuration (e.g., `vhosts`), configure the protected mount with `interceptor-path` pointing to the mount handled by this plugin.
+
+**Example `localhost` vhost config:**
+
+```json
+{
+    "vhosts": [{
+        "name": "localhost",
+        "port": "7681",
+        "ws-protocols": [{
+            "lws_captcha_ratelimit": {
+                "status": "ok",
+                "jwt-jwk": "{\"k\":\"626UazEjGLhz1Kzrdi427lg0Z4cAamGNlz7O1rgFwECsjQBmmcgBYaj-LIK-vJp67gDUnUlq0GL44Br2_kox6VlX8iS24vVaDqrTNuCW-sEM06yJn2BJXDCn-ng3WsliA02U7CLu7UFOPr7kL6kXRGLSKkg0m5LaeyNO7q0vHEZyCLGEdyYCYjzYXhw8gny4qzlYCMsFvt6VoWnOEGeR4AS1J0s8KjCEb30RoQpRIipPdvjWSgVJKHRbOwXg-eE7R1YSUkgOD6ogyEzoDpNxTS2o0CNy0hNykZDYPzca01Smo3BAs3faSFqurtYRxEBhMk1yqkk3GI_jJma19KIfVrQN6vS5IQRyOyonRpH9uwCGm_I-NTquic4SRaBsjPxZ8bmTvtkQ1SgvySWNiMZ2St_F99K4VCXM1ZfUUK2B7aZ3cf4o4ZFh0J46Do8HNfuxvG_OT9B55r3dZ5tvfgbZwURBTWNmnUtDJPfWxswe6eYghU-jYscCdEyxzVWBUc_ujA_DOcFGKLycMOvLXo41Ho4TLHyX65u4ypAciER_QDkx8EGRPQvreByNEp2DLftEiZ02ImTduCpcWehcDBJ_1d3an0x1k4DRWbpk8T1BuanH1o77QUAqGKyW2rTo_IMO0ZE-0JqC_vOKlh46i9Wp9xi73zysDKkqex6MkyqAflE\",\"kty\":\"oct\"}",
+                "jwt-issuer":           "lws-test",
+                "jwt-audience":         "lws-test",
+                "jwt-alg":              "HS256",
+                "jwt-expiry":           600,
+                "cookie-name":          "lws_captcha_jws",
+                "asset-dir":            "file://_lws_ddir_/libwebsockets-test-server/captcha-ratelimit/captcha-assets",
+                "pre-delay-ms":         5000,
+                "post-delay-ms":        3000
+            }
+        }],
+        "mounts": [{
+            "mountpoint": "/",
+            "origin": "/var/www/html",
+            "default": "index.html",
+            "interceptor-path": "/captcha"
+        }, {
+            "mountpoint": "/captcha",
+            "origin": "callback://lws_captcha_ratelimit",
+            "protocol": "lws_captcha_ratelimit"
+        }]
+    }]
+}
+```
+
+Note that you should not use the provided example jwt-jwk in production.
+You can regenerate one with `lws-crypto-jwk -t OCT` and copy it into place in the config.
+
+In this example:
+1.  Requests to `/` (and subpaths) are checked for a valid JWT.
+2.  If invalid, they are diverted to `/captcha`.
+3.  `/captcha` is handled by the `lws_captcha_ratelimit` protocol.
+4.  The plugin serves the interceptor UI.
+5.  Upon success, a cookie is set, and the user is redirected back to `/`.

include/libwebsockets.h

@@ -753,6 +753,9 @@ lws_fx_string(const lws_fx_t *a, char *buf, size_t size);
 #endif
 
 #include <libwebsockets/lws-protocols-plugins.h>
+#if defined(LWS_WITH_JOSE)
+#include <libwebsockets/lws-interceptor.h>
+#endif
 
 #include <libwebsockets/lws-context-vhost.h>
 

include/libwebsockets/lws-callbacks.h

@@ -884,6 +884,14 @@ enum lws_callback_reasons {
 	 * Return nonzero to close the wsi.
 	 */
 
+	LWS_CALLBACK_HTTP_INTERCEPTOR_CHECK				= 213,
+	/**< A mount has a interceptor_path enabled, this callback asks the
+	 * protocol bound to that mount if it is OK for this request to
+	 * proceed.  If returning 0, the request proceeds to the original
+	 * mount.  If nonzero, the request is diverted to the interceptor_path
+	 * mount.
+	 */
+
 	/****** add new things just above ---^ ******/
 
 	LWS_CALLBACK_USER = 1000,

include/libwebsockets/lws-context-vhost.h

@@ -1433,6 +1433,12 @@ struct lws_http_mount {
 		/**< 0 or seconds http stream should stay alive while
 		 * idle.  0 means use the vhost value for keepalive_timeout.
 		 */
+#if defined(LWS_WITH_JOSE)
+	const char *interceptor_path;
+	/**< NULL, or an alternative mount path to divert the connection to
+	 * if the protocol on that mount says we are not authorized.
+	 */
+#endif
 
 	/* Add new things just above here ---^
 	 * This is part of the ABI, don't needlessly break compatibility

include/libwebsockets/lws-http.h

@@ -53,6 +53,20 @@
 LWS_VISIBLE LWS_EXTERN const char *
 lws_get_mimetype(const char *file, const struct lws_http_mount *m);
 
+/**
+ * lws_find_mount() - Find the mount context for a URI
+ *
+ * \param wsi:		wsi context
+ * \param uri_ptr:	pointer to the URI
+ * \param uri_len:	length of the URI
+ *
+ * Returns NULL or a pointer to the matching mount.
+ */
+#if defined(LWS_ROLE_H1) || defined(LWS_ROLE_H2)
+LWS_VISIBLE LWS_EXTERN const struct lws_http_mount *
+lws_find_mount(struct lws *wsi, const char *uri_ptr, int uri_len);
+#endif
+
 /**
  * lws_serve_http_file() - Send a file back to the client using http
  * \param wsi:		Websocket instance (available from user callback)
@@ -559,6 +573,39 @@ lws_get_urlarg_by_name_safe(struct lws *wsi, const char *name, char *buf, int le
 LWS_VISIBLE LWS_EXTERN const char *
 lws_get_urlarg_by_name(struct lws *wsi, const char *name, char *buf, int len)
 /* LWS_WARN_DEPRECATED */;
+
+/**
+ * lws_http_remove_urlarg() - remove a named urlarg from the header table
+ *
+ * \param wsi: the connection to check
+ * \param name: the arg name to remove, eg "token" or "token="
+ *
+ * This removes the named argument from the WSI_TOKEN_HTTP_URI_ARGS fragment
+ * chain in the header table (ah).  It does not reclaim space in the ah data
+ * area, but the argument will no longer be visible to subsequent protocols
+ * handling the same wsi.
+ *
+ * Returns 0 if removed, else nonzero.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_http_remove_urlarg(struct lws *wsi, const char *name);
+
+/**
+ * lws_http_zap_header() - remove a named header from the header table
+ *
+ * \param wsi: the connection to check
+ * \param name: the header name to remove, eg "X-Auth-User"
+ *
+ * This removes the named header from the header table (ah). It handles both
+ * recognized tokens and unknown custom headers. Note that it does not reclaim
+ * space in the ah data area, but the header will no longer be visible to
+ * subsequent protocols or forwarded during proxying.
+ *
+ * Returns 0 if removed or not found, else nonzero.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_http_zap_header(struct lws *wsi, const char *name);
+
 ///@}
 
 /*! \defgroup HTTP-headers-create HTTP headers: create

include/libwebsockets/lws-interceptor.h

@@ -0,0 +1,105 @@
+#include <stddef.h>
+#if defined(LWS_WITH_JOSE)
+/*
+ * libwebsockets - small server side websockets and web server implementation
+ *
+ * Copyright (C) 2010 - 2025 Andy Green <andy@warmcat.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+/** \defgroup captcha Captcha
+ * ##Captcha API
+ *
+ * Lws provides a generic captcha "engine" that handles JWT sessions,
+ * redirection flows, and asset serving. Captcha implementations (puzzles,
+ * ratelimits, etc) provide a `struct lws_captcha_ops` to customize the
+ * behavior.
+ */
+/**@{*/
+
+typedef enum {
+	LWS_INTERCEPTOR_RET_REJECT	= 0, /* Failed the challenge */
+	LWS_INTERCEPTOR_RET_PASS	= 1, /* Passed immediately */
+	LWS_INTERCEPTOR_RET_DELAYED	= 2, /* Use a timer before passing (for ratelimiting) */
+} lws_interceptor_result_t;
+
+struct lws_interceptor_ops {
+	const char *name;		/* e.g., "ratelimit" or "puzzle" */
+
+	/**
+	 * [Optional] Add implementation-specific dynamic JS variables to
+	 * the automatically served "captcha-config.js".
+	 */
+	int (*get_config_js)(struct lws *wsi, char *buf, size_t len);
+
+	/**
+	 * [Optional] Customize the "visit" JWT claims.
+	 * e.g., Store a random math problem or puzzle seed here.
+	 */
+	int (*init_visit_cookie)(struct lws *wsi, char *buf, size_t len);
+
+	/**
+	 * Verify the POSTed challenge submission.
+	 * Decides if the user passes, fails, or needs to wait.
+	 */
+	lws_interceptor_result_t (*verify)(struct lws *wsi, const void *data, size_t len);
+
+	/**
+	 * [Optional] Extra logic to run if verify returned LWS_INTERCEPTOR_RET_DELAYED
+	 * and the timer expired.
+	 */
+	void (*on_delay_expired)(struct lws *wsi);
+};
+
+/**
+ * lws_interceptor_check() - Check if a valid interceptor session exists
+ *
+ * \param wsi: the connection to check
+ *
+ * Returns 0 if a valid interceptor session exists (JWT cookie present and valid for IP),
+ * non-zero if a interceptor diversion is required.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_interceptor_check(struct lws *wsi, const struct lws_protocols *prot);
+
+/**
+ * lws_interceptor_handle_http() - Generic HTTP handler for interceptor plugins
+ *
+ * \param wsi: the connection
+ * \param user: PSS
+ * \param ops: the interceptor implementations ops
+ *
+ * This handles serving assets, config JS, and processing POST submissions
+ * using the provided wheat.
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_interceptor_handle_http(struct lws *wsi, void *user, const struct lws_interceptor_ops *ops);
+
+/**
+ * lws_callback_interceptor() - Generic protocol callback for interceptor plugins
+ */
+LWS_VISIBLE LWS_EXTERN int
+lws_callback_interceptor(struct lws *wsi, enum lws_callback_reasons reason,
+		     void *user, void *in, size_t len,
+		     const struct lws_interceptor_ops *ops);
+
+/**@}*/
+
+#endif