ALTCHA

ALTCHA uses a proof-of-work mechanism to protect your website, APIs, and online services from spam and abuse. Unlike other solutions, ALTCHA is self-hosted, does not use cookies nor fingerprinting, does not track users, and is fully compliant with GDPR.

https://altcha.org

Benefits

• Friction-less - Using PoW instead of visual puzzles.
• Cookie-less - GDPR compliant by design.
• Self-hosted - Without reliance on external providers.

Usage

ALTCHA widget is distributed as a "Web Component" and supports all modern browsers.

1. Install ALTCHA

npm install altcha

import altcha in your main file:

import 'altcha';

or insert <script> tag to your website:

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

CDN: https://cdn.jsdelivr.net/gh/altcha-org/altcha@main/dist/altcha.min.js

2. Use <altcha-widget> tag in your forms

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

See the configuration below or visit the website integration documentation.

3. Integrate ALTCHA with your server

See server documentation for more details.

Configuration

Required options (at least one is required):

• challengeurl - URL of your server to fetch the challenge from. Refer to server integration.
• challengejson - JSON-encoded challenge data. If avoiding an HTTP request to challengeurl, provide the data here.

Additional options:

• auto - Automatically verify without user interaction (possible values: onfocus, onload, onsubmit).
• blockspam - Only used in conjunction with the spamfilter option. If enabled, it will block form submission and fail verification if the Spam Filter returns a negative classification. This effectively prevents submission of the form.
• expire - The challenge expiration (duration in milliseconds).
• hidefooter - Hide the footer (ALTCHA link).
• hidelogo - Hide the ALTCHA logo.
• maxnumber - The max. number to iterate to (defaults to 1,000,000).
• name - The name of the hidden field containing the payload (defaults to "altcha").
• spamfilter - Enable Spam Filter.
• strings - JSON-encoded translation strings. Refer to customization.
• refetchonexpire - Automatically re-fetch and re-validate when the challenge expires (defaults to true).
• verifyurl - Enable server-side verification by configuring the URL to use for verification requests. This option can be used in conjunction with spamfilter to enable server-side verification.
• workers - The number of workers to utilize for PoW (defaults to navigator.hardwareConcurrency || 8).

Development / testing options:

• debug - Print log messages in the console.
• mockerror - Causes the verification to always fail with a "mock" error.
• test - Generates a "mock" challenge within the widget, bypassing the request to challengeurl.

Programmatic Configuration

To configure the widget programmatically, use the configure() method:

document.querySelector('#altcha').configure({
  challenge: {
    algorithm: 'SHA-256',
    challenge: '...',
    salt: '...',
    signature: '...',
  },
  strings: {
    label: 'Verify',
  },
});

Available configuration options:

export interface Configure {
  auto?: 'onload' | 'onsubmit'; 
  challenge?: {
    algorithm: string;
    challenge: string;
    salt: string;
    signature: string;
  };
  debug?: boolean;
  expire?: number;
  hidefooter?: boolean;
  hidelogo?: boolean;
  maxnumber?: number;
  mockerror?: boolean;
  name?: string;
  refetchonexpire?: boolean;
  spamfilter: boolean | SpamFilter;
  strings?: {
    error?: string;
    footer?: string;
    label?: string;
    verified?: string;
    verifying?: string;
    waitAlert?: string;
  };
  test?: boolean | number;
  verifyurl?: string;
  workers?: number;
}

Events

• serververification - Triggers upon a server verification (only in conjunction with spamfilter).
• statechange - Triggers whenever an internal state changes.
• verified - Triggers when the challenge is verified.

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

Using events:

document.querySelector('#altcha').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', ...).

Spam Filter

The widget integrates with ALTCHA's Spam Filter API to allow checking submitted form data for potential spam.

The Spam Filter API analyzes various signals in the submitted data to determine if it exhibits characteristics of spam. This non-invasive filtering helps reduce spam submissions without frustrating legitimate users.

Spam Filter Configuration

The Spam Filter can be enabled with default configuration by setting the spamfilter option to true, or it can be customized using the following configuration schema:

interface SpamFilter {
  email?: string | false;
  expectedLanguages?: string[];
  expectedCountries?: string[];
  fields?: string[] | false;
  ipAddress?: string | false;
  timeZone?: string | false;
}

SpamFilter configuration options:

• email - The name of the input field for the user's email. Disable email checking with false.
• expectedLanguages - An array of expected languages as 2-letter codes (ISO 639 alpha-2).
• expectedCountries - An array of expected countries as 2-letter codes (ISO 3166-1 alpha-2).
• fields - An array of input names to send to the spam filter.
• ipAddress - The user's IP is detected automatically but can be overridden or disabled with false.
• timeZone - The user's timezone is detected automatically but can be overridden or disabled with false.

Exclude Inputs from Spam Checking

By default, all text inputs and textareas within the parent form are spam-checked. To exclude a specific input, add the data-no-spamfilter attribute. Alternatively, explicitly list the checked fields using the fields config option.

Contributing

See Contributing Guide and please follow our Code of Conduct.

License

MIT