omnishield/altcha

ALTCHA as an Omnishield captcha: a proof of work the site issues and checks itself, over altcha-org/altcha (the PHP library, ^2.3) and the altcha widget 3.3.0 (npm, MIT). The visitor's browser derives keys until one starts as the challenge asks; the site checks the one it found. It calls nothing: no third party, no cookie, no consent to ask - the family's default. Since ALTCHA cannot tell a solution it saw before, the gateway remembers each one in the store of spent tokens it is given.

Installation

composer require omnishield/altcha

PHP 8.2 or later, omnisense/omnishield and altcha-org/altcha ^2.3. No HTTP client: this package calls nothing.

use Omnishield\Altcha\AltchaGatewayFactory;
use Omnishield\Replay\CacheReplayStore;

$gateway = (new AltchaGatewayFactory(new CacheReplayStore($psr6Pool)))->create(['hmac_key' => getenv('ALTCHA_HMAC_KEY')]);

Credentials

None from anyone: an hmac_key of the site's own - long, random, secret, from the environment or the secrets vault - signs the challenges. Changing it makes the challenges already in pages invalid (invalidSignature).

The sources

Written on 2026-10-07 from the library's own code and README at v2.3.0 (Altcha::createChallenge(), solveChallenge(), verifySolution(), Payload, CreateChallengeOptions), and from the widget's README and code, altcha 3.3.0 on npm (its attributes, the inline JSON challenge it accepts, the base64 payload it posts in the altcha field).

How it goes

1. widget($action) - or issue($action), behind a route - makes a challenge: random nonce and salt, a key derivation (PBKDF2/SHA-256 by default) and its cost, the prefix the derived key must start with, an expiry, and {"action": ..., "issued": ...} in its data - all of it signed with HMAC-SHA-256 under the site's hmac_key.
2. The widget's workers try counters until a derived key starts with the prefix, and post {"challenge": ..., "solution": {"counter", "derivedKey"}}, base64, in the altcha field.
3. verify() checks the signature, the expiry, the solution (one derivation), the action - and spends the challenge's signature in the store: the second post is duplicate.

Verdict::$action is the action it was issued for, $at when it was issued; no score, no host: ALTCHA does not know where the widget was shown.

Options

new AltchaGatewayFactory(?ReplayStoreInterface $replays = null): the store of spent tokens, shared by every request (CacheReplayStore on a PSR-6 pool, or one of the site's on an atomic store); none is this process's memory (InMemoryReplayStore), right in a test or a worker, not behind PHP-FPM. AltchaGatewayFactory::algorithm($name) gives the library's key derivation of a name (a solver of your own, the tests).

Capabilities

The widget is printed as <script type="module" async defer> and <altcha-widget challenge="..." name="altcha">.

The script: the site's own

The widget's script - altcha 3.3.0's dist/main/altcha.min.js, MIT - is shipped in this package (public/altcha.min.js, its licence beside it, AltchaGatewayFactory::SCRIPT_FILE), unchanged: its integrity is sha256-/CeoPc2Yo9is9tcPvkZD3L7lEqv7mIhu3Y7QRTUK2Ck= (AltchaGatewayFactory::INTEGRITY), the same as the CDN's. It loads nothing else: its workers are data: URLs (worker-src 'self' data: in a Content-Security-Policy).

In a Symfony application the bridge serves it at /omnishield/altcha/3.3.0/altcha.min.js (AltchaGatewayFactory::SCRIPT_PATH, cached a year) and makes that the gateways' default: the widget reaches nobody - Widget::$origins is empty, reachesOthers() false, no consent to ask. Nothing to install, no route to import, no asset pipeline. omnishield.serve_scripts: false goes back to the CDN.

In PHP alone the default stays jsDelivr, pinned and checked (AltchaGatewayFactory::SCRIPT): Widget::$origins then names https://cdn.jsdelivr.net - a CDN sees the visitor's address, though the check itself stays on the site (thirdParty: false). Serve the package's copy yourself and nobody does:

cp vendor/omnishield/altcha/public/altcha.min.js public/js/altcha.min.js

$gateway = (new AltchaGatewayFactory($store))->create(['hmac_key' => getenv('ALTCHA_HMAC_KEY'), 'script' => '/js/altcha.min.js']);

Its texts, in the visitor's language

The script carries English only. Its texts - "I'm not a robot", "Verifying...", "Verified", "Verification failed. Try again later.", the footer "Protected by ALTCHA" and the others of AltchaGateway::TEXTS - are given to it by a short script printed after the element (Widget::$inline, its nonce with the others), which registers them with the widget (globalThis.$altcha.i18n) for its language; a text left out stays the widget's English.

In a Symfony application the bridge does it for every widget it prints: the request's locale, the texts of its translation domain omnishield (altcha.label, altcha.verifying...), shipped in French, English, German and Japanese - an application's translations/omnishield.<locale>.yaml overrides any of them, or adds a language. The language option fixes the widget's language whatever the visitor's; the strings option wins over the translations:

omnishield:
    gateways:
        forms:
            factory: altcha
            options:
                hmac_key: '%env(ALTCHA_HMAC_KEY)%'
                strings: { label: "Je ne suis pas un robot, promis" }

In PHP alone give them as options, or to localized():

$gateway = $factory->create(['hmac_key' => $key, 'language' => 'fr', 'strings' => ['label' => 'Je ne suis pas un robot', 'verifying' => 'Vérification…', 'verified' => 'Vérifié']]);
$french = $gateway->localized('fr', $texts);   // a copy; the gateway's own language and strings still win

In the page, or from a route

Without challenge_url the challenge travels in the page, as the widget's challenge attribute (JSON). A page served from a cache would give everyone the same challenge - the first to post it spends it: let the widget fetch a fresh one, from the Symfony bridge's route (/omnishield/<gateway>/challenge) or one of yours that answers $gateway->issue($action) with Cache-Control: no-store.

Example

A widget in French, its challenge solved by the library's own solver (what the browser does), then posted twice and for another action (run in omnishield's workspace on 2026-10-26, offline - the date printed is that run's):

<?php

require 'vendor/autoload.php';

use AltchaOrg\Altcha\Altcha;
use AltchaOrg\Altcha\Challenge;
use AltchaOrg\Altcha\Payload;
use AltchaOrg\Altcha\SolveChallengeOptions;
use Omnishield\Altcha\AltchaGatewayFactory;
use Omnishield\Model\Attempt;
use Omnishield\Replay\InMemoryReplayStore;

$altcha = (new AltchaGatewayFactory(new InMemoryReplayStore()))->create(['hmac_key' => 'a-long-random-secret-of-the-site', 'language' => 'fr', 'strings' => ['label' => 'Je ne suis pas un robot']]);
$widget = $altcha->widget('contact');
echo $widget->tag, ' posting "', $widget->field, '", origins: ', implode(', ', $widget->origins), ', texts: ', $widget->inline ? 'yes' : 'no', "\n";

// The browser's part, done here by altcha-org/altcha's own solver.
$solve = static function (array $issued): string {
    $challenge = Challenge::fromArray($issued);
    $solution = (new Altcha())->solveChallenge(new SolveChallengeOptions(challenge: $challenge, algorithm: AltchaGatewayFactory::algorithm('PBKDF2/SHA-256')));

    return (new Payload($challenge, $solution))->toBase64();
};
$token = $solve(json_decode($widget->attributes['challenge'], true));
foreach (['contact', 'contact'] as $action) {
    $verdict = $altcha->verify(new Attempt($token, action: $action));
    echo $verdict->passed ? 'passed, issued at '.$verdict->at->format(DATE_ATOM) : 'refused ('.implode(', ', $verdict->reasons).')', "\n";
}
echo 'another action: ', implode(', ', $altcha->verify(new Attempt($solve($altcha->issue('signup')), action: 'contact'))->reasons), "\n";
echo 'garbage: ', implode(', ', $altcha->verify(new Attempt('not-a-payload'))->codes), "\n";

altcha-widget posting "altcha", origins: https://cdn.jsdelivr.net, texts: yes
passed, issued at 2026-10-25T23:46:40+00:00
refused (duplicate)
another action: action
garbage: malformed

In Symfony, with the challenge fetched from the bridge's route (the page may then be cached):

omnishield:
    gateways:
        forms:
            factory: altcha
            options: { hmac_key: '%env(ALTCHA_HMAC_KEY)%', challenge_url: /omnishield/forms/challenge }

Errors

ALTCHA calls nothing, so it is never unreachable and never refuses a key: a token that does not hold is a Verdict (the table above). InvalidConfigException at create(): hmac_key missing or empty, an unknown algorithm, a key_prefix that is not hexadecimal.

Verified, and not

Responsibility

ALTCHA here reaches no service: the challenge is issued and checked by the site. The widget's script is the work of Daniel Regeci and BAU Software s.r.o., under the MIT License, shipped unchanged with its licence (public/altcha.LICENSE.txt); the PHP library is altcha-org/altcha's. This package is not affiliated with their authors; its MIT licence covers its own code.