README

Self-hosted, privacy-friendly Altcha (proof-of-work) provider for the O3-Shop core CAPTCHA layer. No third-party calls, no tracking, no operator account — GDPR-clean by design.

The module ships no forms, templates or blocks — storefront widget rendering and the admin CAPTCHA screen live in O3-Shop core. This module contributes one CAPTCHA provider (plus a challenge endpoint and the self-hosted widget asset), wired in via the oxid.captcha.provider DI tag.

Requirements

• PHP 8.1+ (depends on altcha-org/altcha, which requires php >= 8.1).
• O3-Shop with the core pluggable CAPTCHA layer (CaptchaProviderInterface + oxid.captcha.provider).

Install

composer require o3-shop/altcha-module
./vendor/bin/oe-console oe:module:activate o3altcha

Configure

In Admin → CAPTCHA: select Altcha, optionally adjust Difficulty (max random number; low ≈ 50000, medium ≈ 100000, high ≈ 500000). The per-shop HMAC secret is auto-generated on first use and never sent to the browser.

Because Altcha is proof-of-work and makes no third-party calls, it is consent-exempt: it is never gated by the core cookie-consent modes.

Three modes

Set Mode to select the operating mode (local is the default).

1. This shop is the Altcha server (local, default). Leave Challenge URL empty. The shop issues challenges at index.php?cl=altcha_challenge, signed with an auto-generated per-shop HMAC secret. No external network calls.

2. External self-hosted Altcha server (external). Set Mode to external, Challenge URL to your Altcha server's challenge endpoint, and Shared HMAC secret to the HMAC key that server signs with. The widget fetches challenges from your server; the shop still verifies solutions locally with the shared secret (no verify-time API call). The Difficulty setting applies only in mode 1 (in mode 2 the external server controls difficulty).

   Both fields are required for external mode. If you set a Challenge URL but leave the Shared HMAC secret empty, the widget loads against the external server but the shop verifies with its own local secret, so every submission is rejected. The module logs a WARNING in this case — check the shop log if an external-mode form rejects all submissions.

3. ALTCHA Sentinel (self-hosted bot-detection server). Set Mode to sentinel, Challenge URL to your Sentinel challenge endpoint, and Sentinel API-key secret to the key secret. The widget talks to Sentinel; Sentinel returns a signed verdict which the shop verifies locally with verifyServerSignature (no verify-time API call), so Sentinel's bot/spam detection gates submissions.

   The Sentinel API-key secret is required for sentinel mode. Without it the shop cannot verify Sentinel's signed response and every submission will be rejected. The module logs a WARNING in this case — check the shop log if a sentinel-mode form rejects all submissions.

Adding Altcha to a new form

No module changes are needed. A form is protected automatically once:

1. its form-id is registered in the core CaptchaFormRegistry, and
2. its template calls [{$oViewConf->getCaptchaWidget('<formId>')}], and
3. its controller calls verifyForForm('<formId>', Registry::getRequest()) before processing.

When Altcha is the active provider, that form then renders the <altcha-widget> and verifies the posted altcha solution server-side.

How it works

License

GPL-3.0