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, DPDPA, and PIPL
• Accessibility standards: WCAG 2.2 AA-level and the European Accessibility Act

For more details, visit altcha.org.

Playground

Want to see it in action? Visit the official ALTCHA Playground to experiment with widget configurations, fine-tune the Proof-of-Work (PoW) settings, and see how the security mechanisms hold up in real-time.

Open ALTCHA Playground

Features

• Frictionless Experience: Eliminates frustrating visual puzzles by using background Proof-of-Work (PoW) for a seamless user journey.
• Hardware-Resistant Security: Leverages Argon2 and Scrypt memory-bound algorithms to neutralize hardware acceleration (ASICs/GPUs) and sophisticated bot farms.
• Accessible Code Challenges: Provides "Enter code from image" fallbacks with built-in audio support for visually impaired users.
• Privacy by Design: Fully GDPR compliant and cookie-free—no tracking, no fingerprinting, and no data collection.
• Universal Accessibility: Engineered to exceed WCAG 2.2 AA standards, ensuring compliance with the European Accessibility Act (EAA).
• Lightweight: Minimal footprint, optimized for rapid page loads and high-performance environments.
• 100% Self-Hosted: Maintain full sovereignty over your infrastructure with no reliance on third-party API availability.

What’s New in v3

• Next-Gen PoW: Significant performance gains and reduced CPU overhead through an optimized verification mechanism.
• Advanced Bot Defense: Native support for Argon2 and Scrypt, raising the cost of attack for automated scripts and specialized hardware.
• Modern UI: Refined styling options, including a suite of new built-in themes and improved CSS custom property support.
• Developer Experience: Improved TypeScript support and streamlined integration.

Migrating from v2

See MIGRATION-v2.md.

Examples

Explore starter templates for popular frameworks:

• React
• Vue
• Svelte
• Solid
• Lit
• Angular

Server Integrations

• TypeScript
• Dart
• PHP
• Go
• Python
• Java
• Ruby
• Elixir
• Rust
• C++

Plugins & CMS

• Libraries and plugins

Usage

The ALTCHA widget is distributed as a Web Component.

1. Install ALTCHA

npm install altcha

Import in your main file:

import 'altcha';

Or load via <script> tag:

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

2. Add <altcha-widget> to Your Forms

<form>
	<altcha-widget challenge="https://..."></altcha-widget>
</form>

See configuration options or the website integration docs.

3. Integrate with Your Server

Refer to the server documentation for implementation details.

Supported Browsers

ALTCHA works on modern browsers with Web Crypto API support (specifically crypto.subtle - caniuse.com).

Supported:

• Chrome 67+ (desktop & Android)
• Edge 79+
• Firefox 63+ (desktop & Android)
• Safari 11+ (macOS & iOS)
• Any browser supporting Web Components + Web Crypto

Not Supported:

• Internet Explorer 11 (or older)

Bundle Size

ALTCHA is optimized for performance:

Distribution Size (GZIPped) ALTCHA 34 kB ALTCHA with all translations 52 kB Cloudflare Turnstile 85+ kB hCaptcha 250+ kB reCAPTCHA 300+ kB

When GZIPped, it totals about 34 kB, making ALTCHA’s widget about ~90% smaller than reCAPTCHA.

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.

Configuration

Programmatic Configuration

The widget provides a global $altcha object to manage defaults, register new algorithms, or add custom translations.

To update an existing widget instance, use the .configure() method. This is the preferred way to handle complex objects or functions that cannot be passed via HTML attributes.

// Set defaults for all future widget instances:
$altcha.defaults.set({
	challenge: 'https://api.example.com/challenge',
	debug: true
});

// Update a specific instance dynamically:
const widget = document.querySelector('altcha-widget');
widget.configure({
	workers: 2,
	language: 'fr'
});

Attribute Configuration

For simple implementations, the widget supports a subset of configuration options directly as HTML attributes. For more advanced properties, use the programmatic approach above.

Supported Attributes:

<altcha-widget
	auto="off"
	challenge="https://api.example.com/challenge"
	configuration='{"minDuration": 1000}'
	display="standard"
	language="en"
	name="altcha"
	theme="default"
	type="checkbox"
	workers="4"
></altcha-widget>

[!TIP] The configuration attribute accepts a JSON-encoded string, allowing you to pass complex settings directly in your HTML markup.

Core Settings

• name: The name attribute of the hidden input field containing the payload. (Default: "altcha")
• challenge: The challenge data or the URL to fetch a new challenge from.
• type: Visual style of the interaction element ('native', 'checkbox', or 'switch').
• language: The ISO alpha-2 language code for localization (requires corresponding i18n file).
• workers: The number of Web Workers to spawn for proof-of-work calculations.

Automation & Timing

• auto: Determines when verification triggers automatically ('off', 'onfocus', 'onload', or 'onsubmit').
• minDuration: The minimum verification time in milliseconds; adds an artificial delay if the PoW is faster. (Default: 500)
• retryOnOutOfMemoryError: Automatically attempts to restart verification with fewer workers if the browser runs out of memory (Argon2 and Scrypt only).

UI & Display

• display: The visual layout mode ('standard', 'bar', 'floating', 'overlay', or 'invisible').
• barPlacement: Vertical position of the widget when display is set to bar ('bottom' or 'top').
• hideLogo: Hides the ALTCHA logo icon.
• hideFooter: Hides the "ALTCHA" attribution link.
• validationMessage: Custom validation message for the HTML5 setCustomValidity API.

Floating Widget Settings

• floatingAnchor: The element or CSS selector the floating UI attaches to. Defaults to the first submit button.
• floatingPlacement: Preferred position relative to the anchor ('auto', 'bottom', or 'top').
• floatingOffset: Vertical offset in pixels between the UI and its anchor. (Default: 12)
• floatingPersist: Whether the floating widget remains visible after successful verification.
• popoverPlacement: Preferred position of popovers relative to the widget ('auto', 'bottom', or 'top').

Modal & Challenge Settings

• codeChallengeDisplay: UI layout for the code-challenge modal ('standard', 'overlay', or 'bottomsheet').
• overlayContent: CSS selector for an element to be mirrored inside the overlay modal.
• audioChallengeLanguage: Forces a specific language for audio-based challenges.
• disableAutoFocus: Prevents the code-challenge modal from stealing focus when opened.

Advanced & Debugging

• debug: Enables verbose logging in the browser console.
• test: Mocks a successful verification for testing environments.
• mockError: Forces the widget into a failed state for UI testing.
• fetch: A custom fetch implementation for network requests.
• humanInteractionSignature: Whether the collector for HIS is enabled (Default: true).
• setCookie: When configured, sends the payload as a cookie.
• timeout: Verification timeout in milliseconds (Default: 90_000).
• verifyFunction: A custom verification handler that overrides default network verification.

Algorithms

ALTCHA supports multiple proof-of-work algorithms. PBKDF2/* and SHA-* are bundled with the main widget by default. Argon2 and Scrypt are memory-bound algorithms that resist hardware acceleration (ASICs/GPUs) but require importing their workers separately.

Supported algorithms:

• PBKDF2/SHA-256 (default, bundled)
• PBKDF2/SHA-384 (bundled)
• PBKDF2/SHA-512 (bundled)
• SHA-256 (bundled)
• SHA-384 (bundled)
• SHA-512 (bundled)
• ARGON2ID (requires separate worker import)
• SCRYPT (requires separate worker import)

If you use Argon2 or Scrypt, import their workers and register them via the $altcha.algorithms global before the widget initializes.

Adding Argon2 / Scrypt Workers (Vite)

Works with both altcha and altcha/external:

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());

Without Bundler Worker Import Support

If your environment does not support ?worker imports, load the prebuilt worker files directly:

import 'altcha';

$altcha.algorithms.set(
	'ARGON2ID',
	() => new Worker('/path/to/node_modules/altcha/dist/workers/argon2id.js')
);
$altcha.algorithms.set(
	'SCRYPT',
	() => new Worker('/path/to/node_modules/altcha/dist/workers/scrypt.js')
);

Using altcha/external

altcha/external excludes all bundled workers, requiring you to register every algorithm explicitly. Use this for full control over which workers are loaded:

…

Cookies

By default, the widget sends the ALTCHA payload as a form field by creating a hidden input. It can also be configured to send the payload via a cookie.

To enable this behavior, use the setCookie configuration option:

widget.configure({
	setCookie: {
		name: 'altcha',
		path: '/'
	}
});

setCookie accepts the following cookie options:

interface SetCookieOptions {
	domain?: string;
	name?: string;
	maxAge?: number;
	path?: string;
	sameSite?: string;
	secure?: boolean;
}

Server Configuration

When the widget fetches a ch