Widget v3 (Beta)

ALTCHA Widget v3 is a complete rewrite of the component, featuring a redesigned Proof-of-Work (PoW) mechanism focused on protection effectiveness and an enhanced developer experience.

Highlights

• Significant performance improvements.
• Flexible PoW: Supports both CPU and memory-bound algorithms.
• Better Aesthetics: Styling improvements and new built-in themes.
• Developer Experience: Improved TypeScript support and streamlined integration.

Playground

Try the new ALTCHA Widget and explore its functionality firsthand in the Playground.

• Open Playground

New Proof-of-Work Mechanism

The core of v3 is a redesigned PoW mechanism. It introduces a new challenge format and support for multiple algorithms to provide robust, modern security.

The new PoW leverages industry-standard Key Derivation Functions (KDFs):

• PBKDF2 (CPU-focused)
• Argon2 & Scrypt (Memory-bound)

These algorithms offer configurable computational and memory costs to suit different security requirements. For more details, see the Playground documentation.

Memory-Bound Algorithms

By supporting Argon2 and Scrypt, the widget now defends against hardware acceleration (ASICs/GPUs) and sophisticated bot farms.

Unlike standard CPU-bound tasks, memory-bound algorithms shift the cost of the PoW to RAM. While these require a WASM implementation, the ALTCHA widget includes everything out-of-the-box, making it easy to deploy advanced protection without complex configuration.

Performance

The new widget resolves previous performance bottlenecks by replacing JavaScript-based SHA-256 with a native browser implementation via the PBKDF2.

• 40x Faster: Browser verification is significantly quicker with comparable CPU utilization, enabling the use of more complex proofs.
• Optimized Legacy Support: The original SHA-based algorithm has also been optimized, running roughly 5x faster while maintaining backward compatibility.

New PBKDF2

50 ms

New SHA-256

400 ms

Old SHA-256

2,100 ms

Measured for 500,000 SHA-256 operations. Detailed benchmarks are available in the Playground.

Leveling the Playing Field

The new algorithms effectively narrow the performance gap between standard web browsers and optimized solvers. By utilizing native browser APIs and WASM-based memory-bound algorithms, ALTCHA makes it significantly more difficult for attackers to gain a hardware advantage.

PBKDF2/SHA-256

Chrome

1,500 ms

C++

600 ms

cost: 5,000; counter: 5,000

Argon2

Chrome

1,700 ms

C++

1,400 ms

cost: 2; memoryCost: 65,536; counter: 100

Scrypt

Chrome

1,700 ms

C++

1,700 ms

cost: 65,536; memoryCost: 8; counter: 100

SHA-256

Chrome

2,200 ms

C++

600 ms

cost: 5,000; counter: 400

The benchmark uses a C++ solver leveraging OpenSSL. Measured on a MacBook Pro (M3 Pro).

Look & Feel

The styling system has been refactored to use a wider variety of CSS variables, making customization seamless.

CSS & Themes

Refactored CSS and built-in themes allow you to match your brand’s identity instantly.

default

aqua

business

caramel

cupcake

cyberpunk

lime

wireframe

Applying a theme using the theme attribute:

import "altcha/themes/cyberpunk.css";

<altcha-widget theme="cyberpunk"></altcha-widget>;

Checkbox & Switch

Choose between a pre-styled checkbox, a modern switch toggle, or a browser-native checkbox for a lightweight feel.

type="checkbox"

Default styled checkbox.

type="switch"

Animated switch (or toggle) style.

type="native"

Browser "native" checkbox, ideal for custom styling.

Example type attribute usage:

<altcha-widget type="switch"></altcha-widget>

Display Modes

The widget now supports more flexible display options to fit your UI, including new bar and invisible modes for a minimalist footprint.

• standard: The default visible widget.
• floating: The familiar floating bubble from v2.
• overlay: A modal-style overlay.
• bar: New — Displays a narrow bar at the top or bottom of the screen.
• invisible: New — Fully invisible integration without requiring customizations.

Example using the display attribute:

<altcha-widget display="invisible"></altcha-widget>

Code Challenge

For the Code Challenge, a new display mode bottomsheet has been introduced, which pairs perfectly with the invisible widget mode.

Show Bottom-sheet

Obfuscation

The Obfuscation plugin has been updated to integrate seamlessly with the redesigned PoW mechanism. This ensures that hidden data — such as email addresses or phone numbers — benefits from the same robust protection and configurable verification costs provided by the new KDF algorithms.

By leveraging the new mechanism, you can fine-tune the friction required to reveal sensitive information, effectively deterring scrapers while maintaining a smooth experience for legitimate users.

Try the updated Obfuscation plugin in the Playground.

Developer Experience

NPM Package

The altcha package is now an all-in-one solution. It includes helper functions for challenge creation and verification, making it easier to integrate and test.

All-In-One Bundle

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

<altcha-widget></altcha-widget>

External (CSP)

<script>
  import 'altcha/external';
  import 'altcha/altcha.css';
  import Pbkdf2Worker from 'altcha/workers/pbkdf2?worker';

  $altcha.algorithms.set("PBKDF2/SHA-256", () => new Pbkdf2Worker());
</script>

<altcha-widget></altcha-widget>

You can now easily manage challenges on the server or client:

Create Challenge

import { createChallenge, pbkdf2 } from 'altcha/lib';

const challenge = await createChallenge({
  algorithm: 'PBKDF2/SHA-256',
  cost: 5_000,
  deriveKey: pbkdf2.deriveKey
});

Solve Challenge

import { solveChallenge, pbkdf2 } from 'altcha/lib';

const solution = await solveChallenge({
  challenge,
  deriveKey: pbkdf2.deriveKey
});

Verify Solution

import { verifySolution, pbkdf2 } from 'altcha/lib';

const result = await verifySolution({
  challenge,
  deriveKey: pbkdf2.deriveKey,
  solution
});

Server-Side Rendering (SSR)

Support for SSR has been significantly improved. The widget no longer throws errors when rendering in environments that lack customElements support.

The integration strategy varies by framework:

• SvelteKit / Nuxt: Usage is identical to client-side rendering.
• React / Next.js: Integration requires client detection to prevent hydration mismatches, as shown below.

SvelteKit

<script lang="ts">
  import 'altcha';
  import type {} from 'altcha/types/svelte';
</script>

<altcha-widget></altcha-widget>

Next.js

'use client'

import { useSyncExternalStore } from 'react';
import 'altcha';
import type {} from 'altcha/types/react';

export default function Altcha() {
  const isClient = useSyncExternalStore(
    () => () => {},
    () => true,
    () => false
  );

  return isClient
    ? <altcha-widget></altcha-widget>
    : <span>Loading...</span>;
}

Nuxt

<script setup lang="ts">
  import 'altcha';
  import type { WidgetAttributes } from 'altcha/types';
  import type { DefineComponent } from 'vue';

  declare module 'vue' {
    interface GlobalComponents {
      'altcha-widget': DefineComponent<WidgetAttributes>
    }
  }
</script>

<template>
  <div>
    <altcha-widget></altcha-widget>
  </div>
</template>

TypeScript

The NPM package now provides global typings for specific environments (React, Svelte, JSX) and separate exportable types:

import type {} from "altcha/types/react"; // or /svelte, /jsx
import type { WidgetAttributes, Challenge } from "altcha/types";

Bundle Size

ALTCHA v3 maintains a minimal footprint. The “All-in-one” bundle includes both PBKDF2 and SHA algorithms by default. To keep the core package lean, support for Argon2 and Scrypt is modular and can be added programmatically via Web Workers.

Bundle	Size (Gzip)
All-in-one	31 kB
All-in-one (All Languages)	49 kB
Argon2 Worker	15 kB
Scrypt Worker	14 kB

Accessibility (A11y)

Accessibility remains a core priority in ALTCHA. The v3 widget is fully ARIA-compliant and supports standard keyboard navigation and screen readers across all display modes.

Status & Migration

Widget v3 is currently in Beta. While no major breaking changes are expected, it is not yet recommended for production environments.

If you encounter a bug or want to share your feedback, please open an issue on GitHub.

The NPM package is currently available in the beta channel, to install it, use:

npm install altcha@beta

GitHub: github.com/altcha-org/altcha/tree/v3 (branch v3)

Migration Overview

Although v3 is a major rewrite, migration should be smooth for most users:

• Server Compatibility: v3 remains compatible with v2 server-side verification logic when using the legacy SHA-256 algorithm. You can use this widget alongside older versions of the server libraries.
• Updated Libraries: Official server-side libraries are being updated to support the new KDF-based algorithms (PBKDF2, Argon2, Scrypt) natively.
• Breaking Changes: Configuration parameters have been refactored and the obfuscation plugin is not backward-compatible. Depending on the complexity of your integration, some code adjustments will be required to align with the new API.

Sentinel Integration

ALTCHA Sentinel (v1.22.0+) supports the new PoW mechanism. This must be manually enabled in the Security Group using the powVersion and supportedAlgorithms rules:

[
    {
        "action": "set",
        "conditions": [],
        "set": [
            {
                "field": "powVersion",
                "value": "2"
            },
            {
                "field": "supportedAlgorithms",
                "value": "PBKDF2/SHA-256,ARGON2ID"
            }
        ]
    }
]

Supported Security Group Rules

• powVersion: Specifies the PoW version (1 or 2). Version 2 enables the new mechanism.
• supportedAlgorithms: A comma-separated list of algorithms supported by your front-end.
• probabilistic: Enables probabilistic mode instead of deterministic (defaults to false).
• cost: Overrides the algorithm cost parameter.
• memoryCost: Overrides the algorithm memoryCost parameter.
• parallelism: Overrides the algorithm parallelism parameter.
• counter: Overrides the algorithm counter parameter. In deterministic mode, a random counter is selected from a pre-configured range by default.

Implementation Details

• Compatibility: Enabling powVersion: 2 changes the response format for the /v1/challenge endpoint. While the new widget (v3) is backward-compatible with previous PoW versions, the older widget does not support the V2 mechanism.
• Resource Management: To minimize attack vectors involving high-cost challenge generation or verification (specifically with memory-hard algorithms), the server utilizes multi-threading for expensive operations. The system ensures that maximum memory consumption of the PoW mechanism is POW_MAX_THREADS multiplied by POW_MAX_MEMORY.