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.

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 challenge from the server, the server can override widget configuration using either the X-Altcha-Config response header or the configuration property in the challenge response.

Example using the configuration property in the challenge JSON response to force cookie usage:

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

The X-Altcha-Config header must contain a JSON-encoded object with configuration options.

Internationalization (i18n)

ALTCHA supports 50+ languages. You can import individual language translations or a bundle that includes all of them.

Importing Translations

To import all translations:

import 'altcha/i18n/all';

To import specific languages only:

import 'altcha/i18n/de';
import 'altcha/i18n/fr-fr';

Alternatively, you can import the combined bundle, which includes both the widget and all translations:

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:

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

Customizing Translations

You can override default translations by updating the global $altcha registry (globalThis.$altcha.i18n):

import 'altcha/i18n/de';

$altcha.i18n.set('de', {
	...$altcha.i18n.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.

Data Obfuscation

Data obfuscation is supported via an official plugin, which must be imported alongside the widget. This is ideal for protecting sensitive information, such as email addresses, from scrapers until the challenge is solved.

To obfuscate data, run:

npx altcha-lib obfuscate [data]

Programmatic Usage

The plugin exports ObfuscationPlugin with static methods obfuscate and deobfuscate for manual data handling:

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

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

Widget Integration

To use the plugin with the widget, ensure altcha/plugins/obfuscation is imported before the main library. Use the data-obfuscated attribute to provide the Base64-encoded payload:

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

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

Methods

• configure(options) - Configures the widget with the given options. See Configuration options above.
• getConfiguration() - Returns the current configuration.
• getState() - Returns the current state of the widget.
• show() - Displays the widget (used in some display modes).
• hide() - Hides the widget (used in some display modes).
• reset(state?, err?) - Resets the internal state, optionally with an error.
• setState(state, err?) - Manually sets the specified state, optionally with an error.
• updateUI() - Force UI update or reposition, for example for the floating display mode.
• verify() - Initiates the verification process.

Events

• codechallenge - Triggers when code-challenge verification is requested.
• expired - Triggers when the challenge expires.
• load - Triggers when the widget loads. The exported methods become available after this event.
• outofmemory - Triggers when an Out-Of-Memory error is received (Argon2 and Scrypt only).
• serververification -Triggers upon a server verification.
• statechange - Triggers whenever an internal state changes.
• verified - Triggers when the challenge is verified.

enum State {
	CODE = 'code',
	ERROR = 'error',
	VERIFIED = 'verified',
	VERIFYING = 'verifying',
	UNVERIFIED = 'unverified',
	EXPIRED = 'expired'
}

Using events:

document.querySelector('altcha-widget').addEventListener('statechange', (ev) => {
	// See enum State above
	console.log('state:', ev.detail.state);
});

Important

Both programmatic configuration and event listeners have to called/attached after the ALTCHA script loads, such as within window.addEventListener('load', ...).

Contributing

See Contributing Guide and please follow our Code of Conduct.

License

MIT