¶ ALTCHA Spam Protection
Privacy-friendly spam protection for OXID eShop 7.x contact, newsletter, and registration forms using ALTCHA proof-of-work, honeypot fields, content validation (gibberish detection and disposable email blocking), and IP-based rate limiting.
Live Demo: Try all OXID eShop and Shopware plugins by Markus Michalski live — no installation, no risk. demo.markus-michalski.net
¶ What is ALTCHA?
ALTCHA is a self-hosted, privacy-friendly CAPTCHA alternative. Unlike Google reCAPTCHA or hCaptcha:
- No external services - Everything runs on your server
- No cookies - Fully GDPR-compliant without consent banner
- No tracking - No user data is sent anywhere
- No puzzles - Users see a simple checkbox that auto-verifies
- Accessible - WCAG 2.2 AA compliant
¶ How does it work?
Instead of image puzzles, ALTCHA uses Proof-of-Work - the user's browser must solve a small computational challenge (SHA-256 hashing). This takes about 1-2 seconds and happens automatically in the background. Bots would need significant computing power to bypass this at scale.
¶ Features
- ALTCHA Proof-of-Work - Browser-based computational challenge
- Honeypot Fields - Invisible trap fields that catch form-filling bots
- Content Validation - Detects gibberish input through consonant analysis, keyboard sequence detection, and bigram frequency analysis
- Disposable Email Detection - Blocks 63+ known disposable email domains (Guerrillamail, Mailinator, Tempmail, etc.)
- IP Rate Limiting - Database-persistent request throttling per IP
- Replay Attack Prevention - Used challenges are tracked and rejected
- Challenge Endpoint Protection - DoS protection for the challenge API
- Multi-Shop compatible (OXID Enterprise Edition)
- GDPR-Compliant - IP addresses stored as SHA-256 hashes
¶ Protected Forms
- Contact Form (
/kontakt/) - Newsletter Subscription (
/newsletter/) - Registration Form (
/konto-eroeffnen/)
¶ Requirements
- OXID eShop 7.x
- PHP 8.2+
- Valid license
¶ Installation
¶ Via Composer
¶ 1. Add Private Repository
Add the private Composer repository to your shop's composer.json:
{
"repositories": [
{
"type": "composer",
"url": "https://packeton.markus-michalski.net"
}
]
}
Note: Repository credentials will be provided upon license purchase. Private repositories are managed via Packeton.
¶ 2. Install via Composer
composer require mmd/oxid7-altcha-integration
When prompted for authentication, enter the credentials provided with your license.
¶ 3. Activate Module
vendor/bin/oe-console oe:module:activate mmd_altcha
vendor/bin/oe-console oe:cache:clear
Note: When installed via Composer, OXID automatically registers the module from
vendor/. Theoe:module:installcommand is only needed for modules insource/modules/.
¶ Update
Update to the latest version:
composer update mmd/oxid7-altcha-integration
vendor/bin/oe-console oe:cache:clear
¶ Configuration
Module configuration in OXID Admin:
Extensions > Modules > ALTCHA Spam Protection > Settings
¶ Main Settings
| Setting | Default | Description |
|---|---|---|
| Enable Module | On | Master switch for all protection features |
¶ ALTCHA Challenge
| Setting | Default | Description |
|---|---|---|
| Enable ALTCHA | On | Shows "I'm not a robot" checkbox that auto-verifies |
| Max Number (Difficulty) | 50000 | Higher = harder challenge, more CPU time required |
| Expiry Seconds | 300 | How long a challenge is valid (5 minutes default) |
| HMAC Secret | (auto) | Auto-generated if empty. Secret key for signing challenges |
About Challenge Difficulty:
- 10000 - Very fast (~0.5s), lower security
- 50000 - Balanced (~1-2s), recommended
- 100000 - Harder (~3-5s), higher security
- 500000 - Very hard (~10-20s), may frustrate users
¶ Honeypot
| Setting | Default | Description |
|---|---|---|
| Enable Honeypot | On | Adds invisible trap field that catches bots |
| Field Name | website | Name of the honeypot input field |
The honeypot is a hidden form field that legitimate users never see or fill out. Bots that automatically fill all form fields will trigger this trap.
¶ Content Validation
| Setting | Default | Description |
|---|---|---|
| Enable Content Validation | On | Checks form contents for gibberish patterns and blocks disposable email addresses |
Content validation works entirely server-side and requires no additional frontend changes. It is enabled by default and protects all forms automatically.
¶ Rate Limiting
| Setting | Default | Description |
|---|---|---|
| Enable Rate Limiting | On | Limits form submissions per IP address |
| Max Requests | 5 | Maximum submissions per time window |
| Window Minutes | 60 | Rate limit window (1 hour default) |
Note: IP addresses are stored as SHA-256 hashes with HMAC in the database for GDPR compliance. The original IP cannot be reconstructed from the hash.
¶ Challenge Endpoint Protection
| Setting | Default | Description |
|---|---|---|
| Enable Challenge Rate Limit | On | Protects challenge endpoint from DoS attacks |
| Max Challenges | 30 | Maximum challenges per IP per window |
| Window Minutes | 60 | Rate limit window for challenges |
¶ Content Validation in Detail
Content validation is a multi-layered detection system that analyzes form contents for spam patterns. It consists of two main components: Gibberish Detection and Disposable Email Detection.
¶ Gibberish Detection
Gibberish detection analyzes text input in the following form fields:
- First name and last name
- Street and city (during registration)
Six different analysis methods are combined:
| Method | Description | Threshold |
|---|---|---|
| Consonant Ratio | Too many consonants indicate random input | > 75% (> 90% for words up to 7 chars) |
| Keyboard Sequences | Detects keyboard mashing like "asdfgh", "qwerty", "zxcvbn" | 4-6 character sequences |
| Repeating Characters | Identical characters in sequence (e.g. "aaaa") | 3+ identical characters |
| Consecutive Consonants | Unnaturally many consonants without a vowel | 6+ consonants in a row |
| Consonant Clusters | Multiple groups of dense consonants in a word | 2+ clusters of 4+ consonants each |
| Bigram Frequency Analysis | Checks whether letter pairs occur in natural languages | Min. 30% known bigrams (164 reference pairs) |
The detection uses a 2-field threshold: At least 2 form fields must be flagged as suspicious before an input is marked as spam. This minimizes false positives for unusual but legitimate names.
German names with high consonant density (Schmidt, Schwartz, Fritz) as well as international names (Polish, Turkish, French) are correctly recognized as legitimate. The analysis treats umlauts (ae, oe, ue) as vowels and includes 164 common bigrams from multiple languages.
¶ Disposable Email Detection
Blocks registrations and contact requests using disposable email addresses. The integrated blocklist covers 63 known providers, including:
- guerrillamail.com, guerrillamail.de
- mailinator.com, mailinator.net
- tempmail.com, temp-mail.org, temp-mail.de
- yopmail.com, yopmail.fr
- trashmail.com, trashmail.me, trashmail.net
- throwaway.email, discard.email
- and more
The blocklist is maintained statically within the module and extended with updates. Custom domains cannot currently be added via the admin panel.
¶ How Protection Layers Work Together
The module validates submissions in this order (optimized for performance - cheapest check first):
- Honeypot Check (< 1ms) - If the hidden field is filled, reject immediately
- Content Validation (CPU-based) - Check form fields for gibberish and disposable emails
- ALTCHA Verification (~100-500ms) - Verify the proof-of-work solution and detect replay attacks
- Rate Limit Check (~10-50ms) - Check IP-based submission limits
A submission must pass ALL enabled checks to be accepted.
¶ Database Tables
The module creates two database tables:
¶ mmd_altcha_rate_limits
Stores rate limiting data:
ip_hash- HMAC-SHA256 hash of IP addressaction- Action identifier (e.g., "contact_form", "newsletter", "challenge")request_count- Number of requests in current windowwindow_start- Start of current rate limit window
¶ mmd_altcha_used_challenges
Stores used ALTCHA challenges to prevent replay attacks:
challenge_hash- Hash of the used challengeused_at- When the challenge was usedexpires_at- When to delete this entry (automatic cleanup)
¶ API Endpoint
¶ GET index.php?cl=mmd_altcha_challenge&fnc=getChallenge
Returns a new ALTCHA challenge for the widget:
{
"algorithm": "SHA-256",
"challenge": "abc123...",
"maxnumber": 50000,
"salt": "xyz789...",
"signature": "sig..."
}
This endpoint is automatically called by the ALTCHA widget when the form loads.
¶ Template Integration
The module uses OXID 7 Template Extensions to inject the ALTCHA widget and honeypot fields into forms. Templates are located in:
views/twig/extensions/themes/apex/
├── form/
│ ├── contact.html.twig # Contact form integration
│ └── newsletter.html.twig # Newsletter form integration
└── layout/
└── base.html.twig # JavaScript/CSS injection
For the registration form, the protection logic is integrated via a PHP extension (UserComponent) that intercepts the createUser() process. No template changes are required.
¶ ViewConfig Methods
For custom template integrations, these methods are available on oViewConf:
{# Check if features are enabled #}
{% if oViewConf.getAltchaEnabled() %}
{# ALTCHA is active #}
{% endif %}
{% if oViewConf.getHoneypotEnabled() %}
{# Honeypot is active #}
{% endif %}
{# Get configuration values #}
{{ oViewConf.getChallengeUrl() }} {# Challenge endpoint URL #}
{{ oViewConf.getHoneypotFieldName() }} {# Honeypot field name #}
{{ oViewConf.getAltchaStrings() }} {# Localized widget strings #}
¶ Privacy & GDPR
This module is designed with privacy in mind:
| Aspect | Implementation |
|---|---|
| External Services | None - fully self-hosted |
| Cookies | None |
| User Tracking | None |
| IP Storage | HMAC-SHA256 hashed only |
| Data Retention | Automatic cleanup of expired entries |
| Consent Required | No - no personal data processing |
Important: Since no cookies are set and no data is sent to third parties, you do NOT need to add this module to your cookie consent banner.
¶ Comparison with Alternatives
| Feature | ALTCHA (this module) | Google reCAPTCHA | hCaptcha |
|---|---|---|---|
| Self-hosted | Yes | No | No |
| GDPR without consent | Yes | No | No |
| No cookies | Yes | No | No |
| No external requests | Yes | No | No |
| User experience | Auto-verify | Image puzzles | Image puzzles |
| Accessibility | WCAG 2.2 AA | Limited | Limited |
| Content validation | Yes (Gibberish + Email) | No | No |
| Server load | Minimal | External | External |
¶ Troubleshooting
¶ Widget not showing
- Clear OXID cache:
vendor/bin/oe-console oe:cache:clear - Check if "Enable Module" and "Enable ALTCHA" are both ON in settings
- Check browser console for JavaScript errors
- Verify module is activated:
vendor/bin/oe-console oe:module:list
¶ Challenge verification fails
- Check if server time is correct (challenges expire after configured seconds)
- Verify HMAC secret hasn't changed since challenge was generated
- Check if challenge was already used (replay attack prevention)
- Check OXID logs in
source/log/for detailed error messages
¶ Rate limit too strict
Increase "Max Requests" or "Window Minutes" in module configuration.
¶ Honeypot not working
The honeypot relies on bots filling hidden fields. Sophisticated bots might skip hidden fields. Use ALTCHA as primary protection.
¶ Content validation blocks legitimate input
Content validation uses a 2-field threshold - a single unusual name won't trigger an alarm. If false positives still occur:
- Check which fields are affected (first name, last name, street, city)
- The detection is tolerant of German special names (Schmidt, Schwartz) and international names
- If needed, content validation can be disabled in the module settings
The error message shown to the user is generic: "Your input could not be processed. Please check your details." - no details about detected spam patterns are revealed, to avoid giving attackers hints.
¶ Disposable email not detected
The blocklist covers 63 known disposable email providers. New providers are added with module updates. If a specific provider is missing, contact support.
¶ Module not loading after Composer install
vendor/bin/oe-console oe:module:deactivate mmd_altcha
rm -rf var/cache/* source/tmp/*
vendor/bin/oe-console oe:module:activate mmd_altcha
¶ License
Commercial License - Single installation license:
- CE/PE License: One OXID eShop installation
- EE License: One OXID eShop installation incl. all subshops
Development and staging environments included. 12 months free updates.
See LICENSE file for full terms.
¶ Support
For questions and support:
Markus Michalski
Email: support@markus-michalski.net