spryker-eco / captcha-altcha
CaptchaAltcha module
Requires
- php: >=8.3
- ext-sodium: *
- altcha-org/altcha: ^2.3.0
- spryker/captcha: ^1.0.0
- spryker/captcha-extension: ^1.0.0
- spryker/configuration: ^1.6.0
- spryker/kernel: ^3.84.0
- spryker/log: ^3.0.0
- spryker/symfony: ^3.0.0
- spryker/transfer: ^3.27.0
- spryker/zed-request: ^3.0.0
Requires (Dev)
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-16 16:58:00 UTC
README
CaptchaAltcha provides an ALTCHA proof-of-work CAPTCHA provider for the Spryker Captcha module:
signed, context-bound Argon2id challenges, and the altcha-widget assets for the Storefront, the Back Office and the
Merchant Portal. No third-party service is called: challenges are created and verified by the application itself.
Installation
composer require spryker-eco/captcha-altcha
The module needs the sodium PHP extension for Argon2id.
The widget is the npm package altcha, declared in the module's own package.json. Add the module to the npm
workspaces of the project package.json, so npm install installs the widget at the version the module was tested with:
"workspaces": [ "vendor/spryker-eco/captcha-altcha" ]
A project that does not use workspaces adds the dependency to its root package.json instead:
npm install altcha@~3.5.0.
Configuration
config/Shared/config_default.php:
use Spryker\Shared\Captcha\CaptchaConstants; use SprykerEco\Client\CaptchaAltcha\CaptchaAltchaConfig; use SprykerEco\Shared\CaptchaAltcha\CaptchaAltchaConstants; // The Captcha module accepts a solved challenge once; it keeps the spent challenges in Redis. $config[CaptchaConstants::REDIS_PERSISTENT_CONNECTION] = true; $config[CaptchaConstants::REDIS_SCHEME] = getenv('SPRYKER_KEY_VALUE_STORE_PROTOCOL') ?: 'tcp'; $config[CaptchaConstants::REDIS_HOST] = getenv('SPRYKER_KEY_VALUE_STORE_HOST'); $config[CaptchaConstants::REDIS_PORT] = getenv('SPRYKER_KEY_VALUE_STORE_PORT'); $config[CaptchaConstants::REDIS_USER] = getenv('SPRYKER_KEY_VALUE_USERNAME'); $config[CaptchaConstants::REDIS_PASSWORD] = getenv('SPRYKER_KEY_VALUE_PASSWORD'); $config[CaptchaConstants::REDIS_DATABASE] = 7; $config[CaptchaAltchaConstants::KEY_DERIVATION_ALGORITHM] = CaptchaAltchaConfig::KEY_DERIVATION_ALGORITHM_ARGON2ID; $config[CaptchaAltchaConstants::COST] = 2; // Argon2id iterations per key derivation $config[CaptchaAltchaConstants::MEMORY_COST] = 16384; // KiB per key derivation (16 MiB) $config[CaptchaAltchaConstants::MINIMUM_COUNTER] = 20; // the browser derives 20 to 40 keys $config[CaptchaAltchaConstants::CHALLENGE_TTL] = 300; // seconds
The environment settings above are optional and show their defaults. CAPTCHA is off by default: once the secret below
is set, turn on Configuration → Security → CAPTCHA → Enable CAPTCHA in the Back Office. Until then the Back Office
refuses to turn it on: AltchaCaptchaProviderPlugin::isConfigured() returns false while the stored secret is empty or
shorter than 32 characters.
| Setting | Default | Meaning |
|---|---|---|
KEY_DERIVATION_ALGORITHM |
ARGON2ID |
ARGON2ID (memory-hard, resists GPU solvers) or PBKDF2/SHA-256. |
COST |
2 (Argon2id), 1000 (PBKDF2) | Iterations of one key derivation. |
MEMORY_COST |
16384 | Memory of one Argon2id key derivation in KiB. |
MINIMUM_COUNTER |
20 (Argon2id), 1000 (PBKDF2) | The secret counter is drawn from [minimum, 2 × minimum]; the browser derives up to that many keys. |
CHALLENGE_TTL |
300 | A challenge expires this many seconds after it is created. A challenge without an expiry is rejected. |
HMAC secret
The secret that signs the challenges is a secret setting of the Configuration module, on Configuration → Integrations → ALTCHA in the Back Office:
| Setting | Key | Notes |
|---|---|---|
| HMAC Secret | integrations:altcha:credentials:hmac_secret |
Required, at least 32 characters. Stored encrypted, never published to the key-value store. |
console configuration:sync registers the setting; the install recipes run it. Every environment gets its own random
secret from the captcha-altcha:hmac-secret:generate console command:
- When no secret is stored, it generates 32 random bytes, stores them hex-encoded (64 characters) at the global scope and prints that the secret was generated.
- When the stored secret is shorter than 32 characters, which the provider rejects, it replaces it the same way.
- When a secret of 32 characters or more is stored, it keeps it and prints that it was kept, so it is safe to run on every deployment.
- The key of the setting and the minimum length come from
SprykerEco\Shared\CaptchaAltcha\CaptchaAltchaConfig, which the generator and the provider share. - It never prints or logs the secret, and it exits with an error code and the reason when the secret cannot be saved.
Register the command in Pyz\Zed\Console\ConsoleDependencyProvider::getConsoleCommands():
use SprykerEco\Zed\CaptchaAltcha\Communication\Console\CaptchaAltchaHmacSecretGenerateConsole; new CaptchaAltchaHmacSecretGenerateConsole(),
Run it in the install recipe after configuration:sync and the database initialization (setup:init-db), for example
next to the step that initializes the database:
captcha-altcha-hmac-secret-generate: command: 'vendor/bin/console captcha-altcha:hmac-secret:generate'
An administrator can rotate the secret on Configuration → Integrations → ALTCHA in the Back Office. Challenges signed with the previous secret are rejected afterwards, so a visitor who had a login form open solves a new challenge.
Without a secret, or with a shorter one, the provider fails closed and logs an error: no challenge is created, and a
login that requires a CAPTCHA is rejected. With the CAPTCHA mode of the Captcha module set to always, this blocks
every login form, the Back Office login included, so the secret cannot be set there. The install step above prevents
this, and the Back Office refuses to turn the CAPTCHA on without a valid secret. Removing the secret while the CAPTCHA is
on (with Use default on the ALTCHA tab) is not prevented. To recover an environment without a valid secret, run console captcha-altcha:hmac-secret:generate, or turn CAPTCHA
off for the time being without the Back Office:
CAPTCHA_ENABLED=false console configuration:import-environment security:captcha:login:is_enabled=CAPTCHA_ENABLED.
Where challenges are created and verified
The secret can be read only in an application that registers
Spryker\Zed\Configuration\Communication\Plugin\Application\ConfigurationApplicationPlugin:
- The Back Office, the Backend Gateway, the Merchant Portal and the Zed console create and verify challenges
in-process. The Merchant Portal needs the plugin in
Pyz\Zed\MerchantPortalApplication\MerchantPortalApplicationDependencyProvider::getMerchantPortalApplicationPlugins(); the Back Office, the Backend Gateway and the console register it already. Without it, a Zed application goes through the Zed gateway and logs a warning for every challenge and payload. - The Storefront creates and verifies challenges through the Zed gateway
(
/captcha-altcha/gateway/create-captcha-challenge,/captcha-altcha/gateway/verify-captcha-payload), served byCaptchaAltchaFacade. A challenge costs one Zed request, which the Backend Gateway signs; with the challenge URL widget below, that request happens when the user ticks the checkbox, once per tick, not while the page renders.
A challenge is bound to the context of its login form, so a solution is accepted only by the same form:
storefront_customer_login, storefront_agent_login, backoffice_user_login, merchant_portal_user_login and
merchant_portal_agent_login.
The server derives one key when it creates a challenge and none when it verifies one: a key signature (an HMAC derived from the secret) lets the verifier check the solution without repeating the work. With the defaults, creating a challenge costs about 9 ms of CPU time and 16 MiB of memory on the server.
Payloads longer than 4096 bytes are rejected before they are decoded. A valid payload returns its signature as the
replay key; the Captcha module stores it in Redis (captcha:spent:*, until the challenge expires) and accepts the
payload once.
Challenge URL widget
AltchaCaptchaProviderPlugin implements Spryker\Client\CaptchaExtension\Dependency\Plugin\CaptchaChallengeUrlProviderPluginInterface
next to CaptchaProviderPluginInterface. When the Captcha module passes a challenge URL (the rate-limited challenge
endpoint of the application that renders the login form), the plugin returns the URL widget and creates no challenge
while the page renders:
<altcha-widget challenge="<challenge URL>" auto="off"></altcha-widget>
- When the user ticks the checkbox, the widget fetches its challenge from the challenge URL and solves it (about 1 s), and the checkbox shows as ticked; the user then submits the form. That is one challenge per tick; a page render and typing create none.
- When the challenge endpoint answers 429 or 503, the widget shows "Verification failed. Try again later." and the checkbox stays unticked.
- The checkbox is a required field. A form that uses the browser's form validation, like the Back Office login form,
asks the user to tick it and sends nothing. The Storefront login forms (
novalidate) and the Merchant Portal login forms (submitted by Angular) send the form, and theCaptchamodule rejects it with "Please complete the security check." autocomes fromSprykerEco\Client\CaptchaAltcha\CaptchaAltchaConfig::getChallengeUrlWidgetAutoMode():offby default; the widget also supportsonfocus(when the user enters the form),onsubmit(when the user submits the form, which the widget submits once the challenge is solved) andonload. With these values the widget ticks the checkbox itself.- For each request to the challenge endpoint, the
Captchaclient calls the plugin'screateChallengeData(), which creates the challenge and returns its JSON document. On the Storefront it creates the challenge through the Zed gateway, because the secret is readable only in Zed. - A challenge expires
CHALLENGE_TTLseconds after it is created. - The Merchant Portal moves the form fields into its Angular form after the widget mounted, so the widget's own form
listeners are never attached. For the
onsubmitandonfocusvalues, the entry scriptZed/CaptchaAltcha/Presentation/Components/entry.tstherefore binds the start of the widget to the document: withonsubmitit holds a submit until the widget is verified, then submits again; a submit while the widget is verifying is held; after an error or expiry the next submit verifies again. Withonfocusit starts the widget when the focus enters the form while the widget is unverified, failed or expired. A failed verification or submit is logged to the browser console. With the defaultoff, the user starts the widget with its checkbox, which needs no form listener. - A login form without a challenge URL renders the widget with a challenge created while the page renders.
The challenge endpoints, their rate limit and their wiring (the Storefront route provider plugin, anonymous access to
the Back Office and Merchant Portal endpoints) belong to the Captcha module.
Wiring
// src/Pyz/Client/Captcha/CaptchaDependencyProvider.php namespace Pyz\Client\Captcha; use Spryker\Client\Captcha\CaptchaDependencyProvider as SprykerCaptchaDependencyProvider; use Spryker\Client\CaptchaExtension\Dependency\Plugin\CaptchaProviderPluginInterface; use SprykerEco\Client\CaptchaAltcha\Plugin\Captcha\AltchaCaptchaProviderPlugin; class CaptchaDependencyProvider extends SprykerCaptchaDependencyProvider { protected function getCaptchaProviderPlugin(): ?CaptchaProviderPluginInterface { return new AltchaCaptchaProviderPlugin(); } }
Then build the frontends:
console transfer:generate npm run yves # Storefront: the lazy `captcha-altcha` component loads the widget npm run zed # Back Office: js/spryker-zed-captcha-altcha.js npm run mp:build # Merchant Portal: Presentation/Components/entry.ts
The widget ships the PBKDF2 and SHA workers only. Each entry point registers the Argon2id worker
(altcha/workers/argon2id), and the build emits it as a separate chunk. The Merchant Portal build needs webpack worker
parsing enabled (module.parser.javascript.worker), which spryker/zed-ui sets in its webpack configuration.
Deployment requirements
- Secure context. The widget uses Web Crypto, which browsers expose only on HTTPS (and
localhost). - Same-origin assets. Browsers start a worker only from a script of the page's origin: serve the frontend assets from the application host, not from a CDN on another origin.
- Content-Security-Policy. The Argon2id worker compiles WebAssembly. A CSP that sets
script-srcmust allow'wasm-unsafe-eval', and one that setsworker-srcmust allow'self'. WithPBKDF2/SHA-256, the widget starts its workers fromblob:URLs instead, soworker-srcmust allowblob:.