altcha 2.0.0-beta.9 → 2.0.1

package/LICENSE.txt

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 Daniel Regeci
+Copyright (c) 2023 Daniel Regeci, BAU Software s.r.o.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,87 +1,100 @@
-# ALTCHA  
+# ALTCHA
 
 ALTCHA is a self-hosted, privacy-first security solution that protects your websites, APIs, and online services from spam and abuse through an innovative proof-of-work mechanism. Unlike traditional CAPTCHAs that depend on intrusive methods like cookies or fingerprinting, ALTCHA delivers robust protection while respecting user privacy.
 
 ALTCHA is fully compliant with:
 
-- **Global privacy regulations**: GDPR, HIPAA, CCPA, PIPEDA/CPPA, LGPD, and PIPL
-- **Accessibility standards**: [WCAG 2.2 AA-level](https://altcha.org/docs/wcag/) and the [European Accessibility Act](https://altcha.org/docs/european-accessibility-act-2025/)
+- **Global privacy regulations**: GDPR, HIPAA, CCPA, PIPEDA/CPPA, LGPD, DPDPA, and PIPL
+- **Accessibility standards**: [WCAG 2.2 AA-level](https://altcha.org/docs/v2/compliance/wcag/) and the [European Accessibility Act](https://altcha.org/docs/v2/compliance/european-accessibility-act-2025/)
 
-For more details, visit [altcha.org](https://altcha.org).  
+For more details, visit [altcha.org](https://altcha.org).
 
-## Features  
+## Features
 
-- **Frictionless Experience**: Uses proof-of-work (PoW) instead of visual puzzles for a seamless user experience.  
-- **Code Challenge (New in v2)**: Supports accessible code challenges ("enter code from image") with an audio option.  
-- **Cookie-Free Design**: GDPR-compliant by default—no cookies or tracking.  
-- **Fully Accessible**: Meets WCAG 2.2 AA-level standards and complies with the European Accessibility Act (EAA).  
-- **Lightweight**: Minimal bundle size for fast page loads and optimal performance.  
-- **Self-Hosted**: No dependency on third-party services.  
+- **Frictionless Experience**: Uses proof-of-work (PoW) instead of visual puzzles for a seamless user experience.
+- **Code Challenge (New in v2)**: Supports accessible code challenges ("enter code from image") with an audio option.
+- **Cookie-Free Design**: GDPR-compliant by default—no cookies or tracking.
+- **Fully Accessible**: Meets WCAG 2.2 AA-level standards and complies with the European Accessibility Act (EAA).
+- **Lightweight**: Minimal bundle size for fast page loads and optimal performance.
+- **Self-Hosted**: No dependency on third-party services.
 
-## What’s New in v2  
+## What’s New in v2
 
-Version 2 introduces enhanced accessibility, expanded language support, and integration with **ALTCHA Sentinel**—a self-hosted anti-spam solution for websites, apps, and services.  
+Version 2 introduces enhanced accessibility, expanded language support, and integration with **ALTCHA Sentinel**—a self-hosted anti-spam solution for websites, apps, and services.
 
-### Key Improvements in v2  
+### Key Improvements in v2
 
-- **Built-in Internationalization (i18n)** for 48+ languages  
-- **Improved RTL (right-to-left) language support**  
-- **Enhanced WCAG accessibility**  
-- **Support for accessible code challenges** (image + audio options)  
+- **Built-in Internationalization (i18n)** for 48+ languages
+- **Improved RTL (right-to-left) language support**
+- **Enhanced WCAG accessibility**
+- **Support for accessible code challenges** (image + audio options)
 
-## Examples  
+### Migrating from v1
 
-Explore starter templates for popular frameworks:  
+Version 2 (v2) is fully compatible with v1, and minimal migration steps are required. However, be sure to test your integration after updating.
 
-- [React](https://github.com/altcha-org/altcha-starter-react-ts)  
-- [Vue](https://github.com/altcha-org/altcha-starter-vue-ts)  
-- [Svelte](https://github.com/altcha-org/altcha-starter-svelte-ts)  
-- [Solid](https://github.com/altcha-org/altcha-starter-solid-ts)  
-- [Lit](https://github.com/altcha-org/altcha-starter-lit-ts)  
-- [Angular](https://github.com/altcha-org/altcha-starter-angular)  
+- Translations: v2 introduces a new [built-in internationalization (i18n) system](#internationalization-i18n). The use of the `strings` attribute is now discouraged in favor of this new system.
+- [ALTCHA Sentinel](https://altcha.org/docs/v2/sentinel): Sentinel is a new self-hosted solution that replaces the previous SaaS services and the SpamFilter. We recommend migrating to Sentinel for better compliance, enhanced security, unlimited verifications, and an adaptive Captcha with code-challenge support.
 
-## Server Integrations  
+## Examples
 
-- [TypeScript](https://github.com/altcha-org/altcha-lib)  
-- [PHP](https://github.com/altcha-org/altcha-lib-php)  
-- [Go](https://github.com/altcha-org/altcha-lib-go)  
-- [Python](https://github.com/altcha-org/altcha-lib-py)  
-- [Java](https://github.com/altcha-org/altcha-lib-java)  
-- [Ruby](https://github.com/altcha-org/altcha-lib-rb)  
-- [Elixir](https://github.com/altcha-org/altcha-lib-ex)  
+Explore starter templates for popular frameworks:
 
-## Plugins & CMS  
+- [React](https://github.com/altcha-org/altcha-starter-react-ts)
+- [Vue](https://github.com/altcha-org/altcha-starter-vue-ts)
+- [Svelte](https://github.com/altcha-org/altcha-starter-svelte-ts)
+- [Solid](https://github.com/altcha-org/altcha-starter-solid-ts)
+- [Lit](https://github.com/altcha-org/altcha-starter-lit-ts)
+- [Angular](https://github.com/altcha-org/altcha-starter-angular)
 
-- [Libraries and plugins](https://altcha.org/docs/integrations/)  
+## Server Integrations
 
-## Usage  
+- [TypeScript](https://github.com/altcha-org/altcha-lib)
+- [PHP](https://github.com/altcha-org/altcha-lib-php)
+- [Go](https://github.com/altcha-org/altcha-lib-go)
+- [Python](https://github.com/altcha-org/altcha-lib-py)
+- [Java](https://github.com/altcha-org/altcha-lib-java)
+- [Ruby](https://github.com/altcha-org/altcha-lib-rb)
+- [Elixir](https://github.com/altcha-org/altcha-lib-ex)
 
-The ALTCHA widget is distributed as a **Web Component** and [supports all modern browsers](https://developer.mozilla.org/en-US/docs/Web/API/Web_components#browser_compatibility).  
+## Plugins & CMS
 
-### 1. Install ALTCHA  
+- [Libraries and plugins](https://altcha.org/docs/integrations/)
+
+## Usage
+
+The ALTCHA widget is distributed as a **Web Component** and [supports all modern browsers](https://developer.mozilla.org/en-US/docs/Web/API/Web_components#browser_compatibility).
+
+### 1. Install ALTCHA
 
 ```sh
 npm install altcha
 ```
 
-Import in your main file:  
+Import in your main file:
 
 ```js
 import 'altcha';
 ```
 
-Or load via `<script>` tag:  
+Or load via `<script>` tag:
 
 ```html
 <script async defer src="/altcha.js" type="module"></script>
 ```
 
-**CDN**:  
+**CDN**:
+
 ```html
-<script async defer src="https://cdn.jsdelivr.net/gh/altcha-org/altcha@main/dist/altcha.min.js" type="module"></script>
+<script
+  async
+  defer
+  src="https://cdn.jsdelivr.net/gh/altcha-org/altcha@main/dist/altcha.min.js"
+  type="module"
+></script>
 ```
 
-### 2. Add `<altcha-widget>` to Your Forms  
+### 2. Add `<altcha-widget>` to Your Forms
 
 ```html
 <form>
@@ -89,57 +102,58 @@ 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/website-integration).
 
-### 3. Integrate with Your Server  
+### 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/server-integration) for implementation details.
 
-## Supported Browsers  
+## Supported Browsers
 
-ALTCHA works on modern browsers with **Web Crypto API** support (specifically `crypto.subtle` - [caniuse.com](https://caniuse.com/?search=subtle)).  
+ALTCHA works on modern browsers with **Web Crypto API** support (specifically `crypto.subtle` - [caniuse.com](https://caniuse.com/?search=subtle)).
 
-**Supported**:  
+**Supported**:
 
-- Chrome (desktop & Android)  
-- Edge  
-- Firefox (desktop & Android)  
-- Safari (macOS & iOS)  
-- Any browser supporting Web Components + Web Crypto  
+- Chrome 67+ (desktop & Android)
+- Edge 79+
+- Firefox 63+ (desktop & Android)
+- Safari 11+ (macOS & iOS)
+- Any browser supporting Web Components + Web Crypto
 
-**Not Supported**:  
+**Not Supported**:
 
 - Internet Explorer 11 (or older)
 
-## Bundle Size  
+## Bundle Size
 
-ALTCHA is optimized for performance:  
+ALTCHA is optimized for performance:
 
-| Distribution      | Size (GZIPped) |  
-|-------------------|----------------|  
-| ALTCHA (v2.x)     | 26+ kB         |  
-| hCaptcha          | 48+ kB         |  
-| reCAPTCHA         | 270+ kB        |  
+| Distribution                 | Size (GZIPped) |
+| ---------------------------- | -------------- |
+| ALTCHA                       | 29+ kB         |
+| ALTCHA with all translations | 42+ kB         |
+| hCaptcha                     | 48+ kB         |
+| reCAPTCHA                    | 270+ kB        |
 
-When GZIPped, it totals about 26 kB, making ALTCHA’s widget about 90% smaller than reCAPTCHA.
+When GZIPped, it totals about 29 kB, making ALTCHA’s widget about 90% smaller than reCAPTCHA.
 
-## Content Security Policy (CSP)  
+## 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/website-integration).
 
-## Configuration  
+## Configuration
 
 Required options (at least one is required):
 
-- **challengeurl**: Server endpoint to fetch the challenge.  
-- **challengejson**: Preloaded JSON challenge data (avoids HTTP requests).  
+- **challengeurl**: Server endpoint to fetch the challenge.
+- **challengejson**: Preloaded JSON challenge data (avoids HTTP requests).
 
 Additional options:
 
 - **auto**: Automatically verify without user interaction (possible values: `off`, `onfocus`, `onload`, `onsubmit`).
 - **credentials**: Whether to include [credentials](https://developer.mozilla.org/en-US/docs/Web/API/RequestInit#credentials) with the challenge request (possible values: `omit`, `same-origin`, `include`).
 - **customfetch**: A custom `fetch` function for retrieving the challenge.  
-  Accepts `url: string` and `init: RequestInit` as arguments and must return a [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response).  
+  Accepts `url: string` and `init: RequestInit` as arguments and must return a [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response).
 - **delay**: Artificial delay in milliseconds before verification (defaults to 0).
 - **disableautofocus**: If true, prevents the code-challenge input from automatically receiving focus on render (defaults to `false`).
 - **expire**: Challenge expiration duration in milliseconds.
@@ -155,6 +169,7 @@ Additional options:
 - **name**: Name of the hidden field containing the payload (defaults to "altcha").
 - **strings**: JSON-encoded translation strings. Refer to [customization](https://altcha.org/docs/widget-customization).
 - **refetchonexpire**: Automatically re-fetch and re-validate when the challenge expires (defaults to true).
+- **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).
 
@@ -168,47 +183,80 @@ Development / Testing options:
 - **mockerror**: Causes verification to always fail with a "mock" error.
 - **test**: Generates a "mock" challenge within the widget, bypassing the request to `challengeurl`.
 
-## Internationalization (i18n)  
+## Internationalization (i18n)
 
-ALTCHA supports **48+ languages**. Import translations from `altcha/i18n/*`:  
+ALTCHA supports **48+ languages**. You can import individual language translations or a bundle that includes all of them.
+
+### Importing Translations
+
+To import all translations:
+
+```js
+import 'altcha/i18n/all';
+```
+
+To import specific languages only:
 
 ```js
-import 'altcha';
-import 'altcha/i18n/all'; // All languages
-// Or import specific languages:
 import 'altcha/i18n/de';
 import 'altcha/i18n/fr-fr';
 ```
 
-The widget auto-detects language from `<html lang="...">` or `navigator.languages`. Override with the `language` attribute:  
+Alternatively, you can import the combined bundle, which includes both the widget and all translations:
+
+```js
+import 'altcha/i18n';
+```
+
+### Language Detection
+
+The widget automatically detects the language from:
+
+- The `<html lang="...">` attribute
+- The user's browser settings (`navigator.languages`)
+
+To override the language manually, use the `language` attribute:
 
 ```html
 <altcha-widget language="de"></altcha-widget>
 ```
 
-## Code Challenges  
+### Customizing Translations
+
+You can override default translations by updating the global `altchaI18n` registry (`globalThis.altchaI18n` or `window.altchaI18n`):
+
+```js
+import 'altcha/i18n/de';
+
+globalThis.altchaI18n.set('de', {
+  ...globalThis.altchaI18n.get('de'),
+  label: 'Ich bin ein Mensch', // Custom label
+});
+```
+
+## Code Challenges
 
-For additional verification, ALTCHA supports **image/audio code challenges** (e.g., "Enter the code from the image"). This feature requires **ALTCHA Sentinel** or a custom server implementation.  
+For additional verification, ALTCHA supports **image/audio code challenges** (e.g., "Enter the code from the image"). This feature requires [ALTCHA Sentinel](https://altcha.org/docs/v2/sentinel) or a custom server implementation.
 
-## Plugins  
+## Plugins
 
-Extend functionality with plugins:  
+Extend functionality with plugins:
 
 ```js
 import 'altcha/obfuscation'; // Data obfuscation
-import 'altcha/upload';      // File uploads
-import 'altcha';             // Main package
+import 'altcha/upload'; // File uploads
+import 'altcha'; // Main package
 ```
 
-Enable plugins per widget:  
+Enable plugins per widget:
 
 ```html
 <altcha-widget plugins="upload,obfuscation"></altcha-widget>
 ```
 
-### Available Plugins  
+### Available Plugins
 
-- **obfuscation**: Secure sensitive data (emails, phone numbers).  
+- **obfuscation**: Secure sensitive data (emails, phone numbers).
 - **upload**: File uploads with ALTCHA Sentinel or a custom backend.
 
 ## Programmatic Configuration
@@ -229,7 +277,7 @@ document.querySelector('#altcha').configure({
 });
 ```
 
-Available configuration options: 
+Available configuration options:
 
 ```ts
 export interface Configure {
@@ -248,7 +296,9 @@ export interface Configure {
   };
   challengeurl?: string;
   credentials?: 'omit' | 'same-origin' | 'include' | boolean;
-  customfetch?: string | ((url: string, init?: RequestInit) => Promise<Response>);
+  customfetch?:
+    | string
+    | ((url: string, init?: RequestInit) => Promise<Response>);
   debug?: boolean;
   delay?: number;
   disableautofocus?: boolean;
@@ -280,7 +330,7 @@ export interface Configure {
     verified: string;
     verifying: string;
     waitAlert: string;
-  }
+  };
   test?: boolean | number | 'delay';
   verifyurl?: string;
   workers?: number;
@@ -305,7 +355,7 @@ enum State {
   VERIFYING = 'verifying',
   UNVERIFIED = 'unverified',
   EXPIRED = 'expired',
-};
+}
 ```
 
 Using events:
@@ -320,14 +370,14 @@ document.querySelector('#altcha').addEventListener('statechange', (ev) => {
 > [!IMPORTANT]  
 > Both programmatic configuration and event listeners have to called/attached after the ALTCHA script loads, such as within `window.addEventListener('load', ...)`.
 
-## Contributing  
+## Contributing
 
 See [Contributing Guide](https://github.com/altcha-org/altcha/blob/main/CONTRIBUTING.md) and please follow our [Code of Conduct](https://github.com/altcha-org/altcha/blob/main/CODE_OF_CONDUCT.md).
 
-## Sponsorship  
+## Sponsorship
 
-This project is sponsored by [BAUSW.com - Digital Construction Site Diary](https://bausw.com/digital-construction-diary/), promoting transparency and trust in construction projects with real-time documentation.  
+This project is sponsored by [BAUSW.com - Digital Construction Site Diary](https://bausw.com/digital-construction-diary/), promoting transparency and trust in construction projects with real-time documentation.
 
-## License  
+## License
 
-**MIT**  
+**MIT**

package/dist/altcha.d.ts

@@ -1,3 +1,4 @@
+import type { Writable } from 'svelte/store';
 export {};
 
 declare module 'altcha';
@@ -5,8 +6,10 @@ declare module 'altcha';
 declare global {
   var altchaCreateWorker: (url?: string) => Worker;
   var altchaPlugins: any[];
-  var altchaI18n: Record<string, any> & {
-    register: (language: string, translation: Record<string, string>) => void;
+  var altchaI18n: {
+    get: (language: string) => Record<string, string>;
+    set: (language: string, translation: Record<string, string>) => void;
+    store: Writable<Record<string, Record<string, string>>>;
   };
 
   type AltchaState = 'error' | 'expired' | 'verified' | 'verifying' | 'unverified';

package/dist/altcha.i18n.d.ts

@@ -0,0 +1,158 @@
+import type { Writable } from 'svelte/store';
+export {};
+
+declare module 'altcha';
+
+declare global {
+  var altchaCreateWorker: (url?: string) => Worker;
+  var altchaPlugins: any[];
+  var altchaI18n: {
+    get: (language: string) => Record<string, string>;
+    set: (language: string, translation: Record<string, string>) => void;
+    store: Writable<Record<string, Record<string, string>>>;
+  };
+
+  type AltchaState = 'error' | 'expired' | 'verified' | 'verifying' | 'unverified';
+
+  interface AltchaStateChangeEvent extends CustomEvent<{
+    payload?: string;
+    state: AltchaState;
+  }> {}
+
+  interface AltchaVerifiedEvent extends CustomEvent<{
+    payload: string;
+  }> {}
+
+  interface AltchaServerVerificationEvent extends CustomEvent<Record<string, unknown>> {}
+
+  interface AltchaWidgetOptions {
+    auto?: 'off' | 'onfocus' | 'onload' | 'onsubmit';
+    /** @deprecated */
+    blockspam?: boolean;
+    challengeurl?: string;
+    challengejson?: string;
+    credentials?: 'omit' | 'same-origin' | 'include' | boolean | undefined;
+    customfetch?: string | ((url: string, init?: RequestInit) => Promise<Response>);
+    debug?: boolean;
+    delay?: number;
+    disableautofocus?: boolean;
+    expire?: number;
+    floating?: 'auto' | 'top' | 'bottom' | 'false' | '' | boolean;
+    floatinganchor?: string;
+    floatingoffset?: number;
+    floatingpersist?: 'focus' | boolean;
+    hidefooter?: boolean;
+    hidelogo?: boolean;
+    id?: string;
+    language?: string;
+    maxnumber?: number;
+    mockerror?: boolean;
+    name?: string;
+    obfuscated?: string;
+    oncleartext?: (ev: CustomEvent) => void;
+    onload?: (ev: CustomEvent) => void;
+    onstatechange?: (ev: CustomEvent) => void;
+    onverified?: (ev: CustomEvent) => void;
+    onserververification?: (ev: CustomEvent) => void;
+    onupload?: (ev: CustomEvent) => void;
+    onuploadprogress?: (ev: CustomEvent) => void;
+    plugins?: string;
+    refetchonexpire?: boolean;
+    /** @deprecated */
+    spamfilter?: boolean | 'ipAddress';
+    strings?: string;
+    test?: boolean | number;
+    verifyurl?: string;
+    workers?: number;
+    workerurl?: string;
+  }
+
+  interface AltchaWidgetMethods {
+    configure: (options: AltchaWidgetOptions) => void;
+    clarify: () => Promise<void>;
+    getConfiguration: () => AltchaWidgetOptions;
+    getFloatingAnchor: () => HTMLElement | null;
+    getPlugin: <T = unknown>(name: string) => T;
+    getState: () => AltchaState;
+    hide: () => void;
+    repositionFloating: (viewportOffset?: number) => void;
+    reset: (newState?: AltchaState, err?: string | null) => void;
+    setFloatingAnchor: (el: HTMLElement) => void; 
+    setState: (newState: AltchaState, err?: string | null) => void; 
+    show: () => void;
+    verify: () => Promise<void>;
+  }
+
+  interface AltchaWidget extends AltchaWidgetOptions {
+  }
+
+  interface AltchaWidgetCSSProperties extends Partial<CSSStyleDeclaration> {
+    '--altcha-border-width'?: string;
+    '--altcha-border-radius'?: string;
+    '--altcha-color-base'?: string;
+    '--altcha-color-border'?: string;
+    '--altcha-color-text'?: string;
+    '--altcha-color-border-focus'?: string;
+    '--altcha-color-error-text'?: string;
+    '--altcha-color-footer-bg'?: string;
+    '--altcha-max-width'?: string;
+  }
+
+  interface AltchaWidgetReactRefObject<T> {
+    current: T | null;
+  }
+
+  interface AltchaWidgetReact extends AltchaWidget {
+    children?: string | number | Node | DocumentFragment;
+    ref?: AltchaWidgetReactRefObject<HTMLElement>;
+    style?: AltchaWidgetCSSProperties;
+  }
+
+  namespace JSX {
+    interface IntrinsicElements {
+      'altcha-widget': AltchaWidgetReact;
+    }
+  }
+
+  namespace React {
+    namespace JSX {
+      interface IntrinsicElements {
+        'altcha-widget': AltchaWidgetReact;
+      }
+    }
+  }
+
+  namespace svelteHTML {
+    interface IntrinsicElements {
+      'altcha-widget': AltchaWidgetSvelte;
+    }
+
+    interface AltchaWidgetSvelte extends AltchaWidget {
+      style?: string;
+    }
+  }
+}
+
+declare module "react" {
+  namespace JSX {
+    interface IntrinsicElements {
+      'altcha-widget': AltchaWidgetReact;
+    }
+  }
+}
+
+declare module "react/jsx-runtime" {
+  namespace JSX {
+    interface IntrinsicElements {
+      'altcha-widget': AltchaWidgetReact;
+    }
+  }
+}
+
+declare module "react/jsx-dev-runtime" {
+  namespace JSX {
+    interface IntrinsicElements {
+      'altcha-widget': AltchaWidgetReact;
+    }
+  }
+}