refactor: remove widget plugins from the main package

Author: ovx

MIGRATION-v2.3.0.md

@@ -0,0 +1,47 @@
+# Migrating to Version 2.3.0
+
+## Summary
+
+A reported vulnerability, [CVE-2025-65849](https://www.cve.org/CVERecord?id=CVE-2025-65849), is currently marked as *disputed* but is still flagged by vulnerability scanners such as `npm audit`.
+As a result, version **2.3.0** moves the obfuscation and other plugins out of the main package into a new package: `@altcha/plugins`.
+
+## Installation
+
+If you use any plugins (such as obfuscation), install the new package explicitly:
+
+```bash
+npm install @altcha/plugins
+```
+
+If you do **not** use any plugins, no additional installation or code changes are required.
+
+## Migration Steps
+
+Plugins are no longer bundled with the main package and must be imported explicitly from `@altcha/plugins`.
+
+**Before (≤ 2.2.4):**
+
+```js
+import 'altcha/obfuscation';
+import 'altcha';
+```
+
+**After (≥ 2.3.0):**
+
+```js
+import '@altcha/plugins/obfuscation';
+import 'altcha';
+```
+
+If you are not importing any plugins, your existing setup continues to work unchanged.
+
+## Rationale
+
+The reported issue describes a cryptographic limitation (an algebraic bypass) of the AES-GCM authentication mechanism, not an exploitable vulnerability in the widget itself. This limitation cannot be mitigated within the widget’s scope.
+
+To prevent false-positive reports in tools like `npm audit`, the affected obfuscation plugin has been extracted into a separate package. If you do not use obfuscation, version 2.3.0 removes the problematic code entirely. If you do use it, you must accept the documented limitations:
+
+[https://altcha.org/docs/v2/obfuscation/#complexity-and-automation](https://altcha.org/docs/v2/obfuscation/#complexity-and-automation)
+
+Additional context:
+[https://github.com/github/advisory-database/pull/6536#issuecomment-3645647102](https://github.com/github/advisory-database/pull/6536#issuecomment-3645647102)

README.md

@@ -9,6 +9,16 @@ ALTCHA is fully compliant with:
 
 For more details, visit [altcha.org](https://altcha.org).
 
+> [!NOTE]
+> **Breaking change (v2.3.0)**
+>
+> As of version **2.3.0**, the obfuscation and other plugins have been removed from the main package and moved to a separate package: `@altcha/plugins`.
+>
+> If you do not use any plugins, no changes are required.
+>
+> See the [migration guide for v2.3.0](https://github.com/altcha-org/altcha/blob/main/MIGRATION-v2.3.0.md).
+
+
 ## Features
 
 - **Frictionless Experience**: Uses proof-of-work (PoW) instead of visual puzzles for a seamless user experience.
@@ -60,7 +70,7 @@ Explore starter templates for popular frameworks:
 
 ## Plugins & CMS
 
-- [Libraries and plugins](https://altcha.org/docs/integrations/)
+- [Libraries and plugins](https://altcha.org/docs/v2/libraries/)
 
 ## Usage
 
@@ -103,11 +113,11 @@ Or load via `<script>` tag:
 </form>
 ```
 
-See [configuration options](#configuration) or the [website integration docs](https://altcha.org/docs/website-integration).
+See [configuration options](#configuration) or the [website integration docs](https://altcha.org/docs/v2/widget-integration).
 
 ### 3. Integrate with Your Server
 
-Refer to the [server documentation](https://altcha.org/docs/server-integration) for implementation details.
+Refer to the [server documentation](https://altcha.org/docs/v2/server-integration) for implementation details.
 
 ## Supported Browsers
 
@@ -141,7 +151,7 @@ When GZIPped, it totals about 30 kB, making ALTCHA’s widget about 90% smaller
 
 ## Content Security Policy (CSP)
 
-The default bundle includes styles and workers in a single file. For strict CSP compliance, use scripts from `/dist_external`. Learn more in the [documentation](https://altcha.org/docs/website-integration).
+The default bundle includes styles and workers in a single file. For strict CSP compliance, use scripts from `/dist_external`. Learn more in the [documentation](https://altcha.org/docs/v2/widget-integration).
 
 ## Configuration
 
@@ -172,14 +182,14 @@ Additional options:
 - **name**: Name of the hidden field containing the payload (defaults to "altcha").
 - **overlay**: Enables overlay UI mode (automatically sets `auto="onsubmit"`).
 - **overlaycontent**: CSS selector of the HTML element to display in the overlay modal before the widget.
-- **strings**: JSON-encoded translation strings. Refer to [customization](https://altcha.org/docs/widget-customization).
+- **strings**: JSON-encoded translation strings. Refer to [customization](https://altcha.org/docs/v2/widget-customization).
 - **verifyurl**: URL for server-side verification requests. This option is automatically configured with Sentinel. Override this setting only if using a custom server implementation. Supports `fn:function_name` format to call a global JS function instead.
 - **workers**: Number of workers to utilize for PoW (defaults to `navigator.hardwareConcurrency || 8`, max value `16`).
 - **workerurl**: URL of the Worker script (defaults to `./worker.js`, only works with `external` build).
 
 Data Obfuscation options:
 
-- **obfuscated**: The [obfuscated data](https://altcha.org/docs/obfuscation) provided as a base64-encoded string (requires `altcha/obfuscation` plugin). Use only without `challengeurl`/`challengejson`.
+- **obfuscated**: The [obfuscated data](https://altcha.org/docs/v2/obfuscation) provided as a base64-encoded string (requires `altcha/obfuscation` plugin). Use only without `challengeurl`/`challengejson`.
 
 Development / Testing options:
 

package.json

@@ -37,7 +37,6 @@
   "files": [
     "dist",
     "dist_external",
-    "dist_plugins",
     "dist_i18n"
   ],
   "main": "./dist/altcha.umd.cjs",
@@ -52,18 +51,6 @@
       "import": "./dist_external/altcha.css",
       "require": "./dist_external/altcha.css"
     },
-    "./analytics": {
-      "import": "./dist_plugins/analytics.js",
-      "require": "./dist_plugins/analytics.umd.cjs"
-    },
-    "./obfuscation": {
-      "import": "./dist_plugins/obfuscation.js",
-      "require": "./dist_plugins/obfuscation.umd.cjs"
-    },
-    "./upload": {
-      "import": "./dist_plugins/upload.js",
-      "require": "./dist_plugins/upload.umd.cjs"
-    },
     "./external": {
       "import": "./dist_external/altcha.js",
       "require": "./dist_external/altcha.umd.cjs"
@@ -83,10 +70,9 @@
   },
   "scripts": {
     "dev": "vite",
-    "build": "npm run build:bundle && npm run build:external && npm run build:plugins && npm run build:i18n",
+    "build": "npm run build:bundle && npm run build:external && npm run build:i18n",
     "build:bundle": "rimraf dist && vite build && vite build -c vite.bundle-i18n.config.ts && cp src/declarations.d.ts dist/altcha.d.ts && cp src/declarations.d.ts dist/altcha.i18n.d.ts",
     "build:external": "rimraf dist_external && vite build -c vite.external.config.ts && cp src/declarations.d.ts dist_external/altcha.d.ts",
-    "build:plugins": "rimraf dist_plugins && find src/plugins -type f -name '*.ts' | xargs -I {} vite build -c vite.plugins.config.ts -- {}",
     "build:i18n": "rimraf dist_i18n && find src/i18n -type f -name '*.ts' | xargs -I {} vite build -c vite.i18n.config.ts -- {}",
     "preview": "vite preview",
     "check": "svelte-check --tsconfig ./tsconfig.json",

dist_plugins/analytics.d.ts plugins/dist/analytics.d.tsdist_plugins/analytics.d.ts renamed to plugins/dist/analytics.d.ts

@@ -0,0 +1 @@
+declare module 'altcha/index';

dist_plugins/analytics.js plugins/dist/analytics.jsdist_plugins/analytics.js renamed to plugins/dist/analytics.js

@@ -0,0 +1 @@
+

dist_plugins/analytics.umd.cjs plugins/dist/analytics.umd.cjsdist_plugins/analytics.umd.cjs renamed to plugins/dist/analytics.umd.cjs

@@ -0,0 +1 @@
+(function(n){typeof define=="function"&&define.amd?define(n):n()})(function(){"use strict"});