DOCSEARCHbyAlgolia
Submit Docs

ALTCHA Documentation

repository·main·Indexed 25 days ago

https://github.com/altcha-org/altcha

A privacy-first, self-verifying proof-of-work (PoW) CAPTCHA widget designed to protect forms from automated spam and bot attacks without user interaction. Compliant with global regulations including GDPR, HIPAA, CCPA, LGDP, DPDPA, and PIPL, and WCAG accessible. Features include a Web Component implementation, support for Argon2 and Scrypt algorithms, internationalization for over 50 languages, and a data obfuscation plugin.

Tokens
10K
Snippets
14
Records
50
Agent score
83%

What's inside ALTCHA

  1. How the ALTCHA PoW mechanism works

    main

    The ALTCHA Proof-of-Work (PoW) mechanism follows a three-step lifecycle involving the server and the client.

    1. Challenge Creation (Server)

    The server generates a cryptographically secure challenge. This includes the algorithm, cost, nonce, salt, and difficulty targets (keyPrefix or keySignature). The challenge is signed with an HMAC to ensure integrity.

    Optional Parameters:

    • expiresAt: A Unix timestamp for challenge expiration.
    • data: An arbitrary key-value map (object).

    2. Solution Finding (Client)

    The client performs a brute-force search. It iterates through a counter (starting from 0), appending it to the nonce to create a password. It then derives a key using the specified algorithm and parameters. The search stops when the derivedKeyHex starts with the required keyPrefix.

    3. Solution Verification (Server)

    The server validates the solution by performing three checks:

    1. Integrity: Validates the HMAC signature of the challenge parameters.
    2. Expiration: Checks if the current time is past expiresAt.
    3. Correctness: Executes a single KDF calculation using the submitted counter and compares the result to the submitted derivedKey (or validates against keySignature in deterministic mode).

  2. Understand Effort Modes: Deterministic vs Probabilistic

    main

    ALTCHA PoW v2 provides two modes to control how difficulty is enforced and verified:

    Deterministic Effort Mode (Recommended)

    The server precisely defines the exact amount of work. The server precomputes a target derived key for a specific counter and provides a keyPrefix and a keySignature (HMAC). The client must find the exact counter that reproduces the prefix.

    • Client Cost: Predictable (exactly as many iterations as the target counter).
    • Server Cost: Low verification (2 HMACs), but moderate generation (1 KDF).
    • Best for: General-purpose protection, security-sensitive operations, and predictable throttling.
    • Warning: Protect challenge generation with rate-limiting to prevent server-side DoS.

    Probabilistic Effort Mode

    The server defines difficulty using a keyPrefix. The client derives keys with increasing counter values until the output matches the prefix.

    • Client Cost: Variable (luck-based; average time is predictable, but individual attempts vary).
    • Server Cost: Very fast generation (1 HMAC), but moderate verification (1 KDF + 1 HMAC).
    • Best for: High-throughput endpoints, resource-constrained servers (IoT/Edge), and anonymous requests.

  3. How ALTCHA Proof-of-Work (PoW) v2 works

    main

    ALTCHA PoW v2 is a client-side computational puzzle designed to mitigate automated abuse. It uses established Key Derivation Functions (KDFs) like PBKDF2, Argon2id, and Scrypt.

    The system is asymmetric: the client performs computationally expensive key derivations to solve a puzzle, while the server performs a relatively fast and inexpensive verification. This ensures that while bots are slowed down by the cost of computation, legitimate users experience minimal friction and the server remains scalable.

  4. Configure the widget via the server

    main

    The server can override widget configuration when fetching a challenge using two methods:

    1. X-Altcha-Config Header: A JSON-encoded object containing configuration options.
    2. configuration Property: A property within the challenge JSON response.

    Example JSON response with configuration:

    {
	"configuration": {
		"setCookie": {
			"name": "altcha",
			"path": "/submit"
		}
	},
	"parameters": {},
	"signature": "..."
}

  5. Register Argon2 and Scrypt algorithms

    main

    By default, ALTCHA bundles PBKDF2/* and SHA-* algorithms. Memory-bound algorithms like ARGON2ID and SCRYPT require separate worker imports. You must register them via the $altcha.algorithms global before the widget initializes.

    Using Vite: Use the ?worker suffix to import workers.

    Without Bundler Support: Load the prebuilt worker files directly using the new Worker() constructor pointing to the dist/workers/ directory in node_modules.

    import 'altcha'; // or 'altcha/external'
import Argon2idWorker from 'altcha/workers/argon2id?worker';
import ScryptWorker from 'altcha/workers/scrypt?worker';

$altcha.algorithms.set('ARGON2ID', () => new Argon2idWorker());
$altcha.algorithms.set('SCRYPT', () => new ScryptWorker());

  6. Use the Data Obfuscation plugin

    main

    The obfuscation plugin protects sensitive information (like email addresses) from scrapers.

    CLI Usage

    Obfuscate data via the command line:

    npx altcha-lib obfuscate [data]

    Programmatic Usage

    Use the ObfuscationPlugin for manual handling:

    import { ObfuscationPlugin } from 'altcha/plugins/obfuscation';

const obfuscatedData = await ObfuscationPlugin.obfuscate('mailto:hello@example.com');

    Widget Integration

    Import the plugin before the main library and provide the Base64-encoded payload via the data-obfuscated attribute:

    <script>
	import 'altcha/plugins/obfuscation';
	import 'altcha';
</script>

<altcha-widget data-obfuscated="${obfuscatedData}" display="floating"></altcha-widget>

  7. Use `altcha/external` for full control

    main

    The altcha/external package excludes all bundled workers. This is useful for minimizing bundle size or having full control over which algorithms are loaded. When using altcha/external, you must explicitly register every algorithm (including PBKDF2 and SHA) using $altcha.algorithms.set().

    import 'altcha/external';
import Argon2idWorker from 'altcha/workers/argon2id?worker';
import Pbkdf2Worker from 'altcha/workers/pbkdf2?worker';
import ScryptWorker from 'altcha/workers/scrypt?worker';
import ShaWorker from 'altcha/workers/sha?worker';

$altcha.algorithms.set('PBKDF2/SHA-256', () => new Pbkdf2Worker());
$altcha.algorithms.set('PBKDF2/SHA-384', () => new Pbkdf2Worker());
$altcha.algorithms.set('PBKDF2/SHA-512', () => new Pbkdf2Worker());
$altcha.algorithms.set('SHA-256', () => new ShaWorker());
$altcha.algorithms.set('SHA-384', () => new ShaWorker());
$altcha.algorithms.set('SHA-512', () => new ShaWorker());
$altcha.algorithms.set('ARGON2ID', () => new Argon2idWorker());
$altcha.algorithms.set('SCRYPT', () => new ScryptWorker());

  8. Manage Internationalization (i18n)

    main

    ALTCHA supports over 50 languages. You can manage translations in three ways:

    1. Importing Translations

    • All languages: import 'altcha/i18n/all';
    • Specific languages: import 'altcha/i18n/de';
    • Combined bundle (Widget + all translations): import 'altcha/i18n';

    2. Language Detection and Overriding

    The widget automatically detects language from the <html lang="..."> attribute or navigator.languages. To override manually, use the language attribute on the element:

    <altcha-widget language="de"></altcha-widget>

    3. Customizing Translations

    Update the global $altcha.i18n registry to override specific strings:

    import 'altcha/i18n/de';

$altcha.i18n.set('de', {
	...$altcha.i18n.get('de'),
	label: 'Ich bin ein Mensch' // Custom label
});

  9. Migrate from ALTCHA v2 to v3

    main

    Version 3 is a complete rewrite of the widget with a redesigned proof-of-work mechanism. Key breaking changes include:

    • Challenge Configuration: challengeurl and challengejson are replaced by a single challenge attribute, which accepts either a URL or a JSON-encoded challenge.
    • Display Modes: floating and overlay attributes are removed. Use the unified display attribute instead.
    • Configuration: Only a limited set of options can be set via HTML attributes; use the programmatic API for advanced settings.
    • Styling: CSS structure and custom properties have been refactored. Update any custom styles or variables.
    • Obfuscation: The obfuscation plugin is now part of the main altcha package. The @altcha/plugins package is for v2 only. Note that the obfuscation algorithm has changed, so previously generated data must be regenerated.
    • TypeScript: Framework-specific types (React, Svelte, JSX) must now be imported explicitly.

  10. Install ALTCHA via npm or script tag

    main

    You can install ALTCHA as a Web Component using npm or by loading it directly via a <script> tag.

    Using npm:

    npm install altcha

    Then import it in your main entry file:

    import 'altcha';

    Using a script tag:

    <script async defer src="/altcha.js" type="module"></script>
    npm install altcha

  11. Choose the right PoW algorithm for your use case

    main

    Depending on your threat model, choose one of the following:

    • PBKDF2 (Recommended): Best for general-purpose use and wide device compatibility. It uses the browser's native Web Crypto API, making it efficient on everything from low-end mobile devices to high-end desktops without requiring extra WASM binaries.
    • Argon2id: Best for targeted defense against specialized hardware and bot farms. It requires a significant memory footprint, forcing attackers to exhaust physical RAM and capping their concurrent request capacity.
    • Scrypt: A mature, memory-hard alternative. Use this if your infrastructure requires a long-standing standard or if Argon2id is unavailable. Note that it is more susceptible to optimization by modern ASICs via "Time-Memory Trade-offs" compared to Argon2id.
    • SHA: Best for legacy or extremely resource-constrained environments with very limited RAM/CPU. It has the lowest verification cost but is the most vulnerable to GPU acceleration.

  12. Understand the ALTCHA Challenge and Payload data structures

    main

    ALTCHA uses specific data structures for challenges and the resulting solutions:

    Challenge

    A Challenge object contains the parameters required for the Proof-of-Work calculation:

    • parameters: ChallengeParameters (algorithm, nonce, salt, cost, etc.).
    • codeChallenge: Optional object containing image or audio data for visual/audio challenges.

    Solution

    A Solution is generated by the client after solving the challenge:

    • counter: The number of iterations performed.
    • derivedKey: The resulting key string.
    • time: The time taken (optional).

    Payload

    The Payload is what is typically sent to the server for verification, combining the challenge (minus the code challenge) and the solution.