Deutsche Version

Back to overview

ALTCHA: Technical Details

Live Demo: Try this and other plugins live — no installation, no risk: demo.markus-michalski.net

How the checks run

graph TD
    A["Submission / Request"] --> B{"Channel enabled?"}
    B -->|"No"| C["Unprotected"]
    B -->|"Yes"| D{"Target ticked?"}
    D -->|"No"| C
    D -->|"Yes"| E["Rate limit"]
    E -->|"exceeded"| F["429 / rate_limited"]
    E -->|"ok"| G["Honeypot + fill time"]
    G -->|"failed"| H["Reject - form error / 422"]
    G -->|"ok"| I{"Disposable-mail / gibberish active?"}
    I -->|"flagged"| H
    I -->|"off or passed"| J["Verify ALTCHA proof"]
    J -->|"invalid or reused"| H
    J -->|"valid"| K["Submission accepted"]

Rate limit, honeypot, minimum fill time and the content checks run ahead of the proof-of-work verification (cheapest first) through all three enforcement mechanisms alike - a target is checked the same way regardless of which path reaches it.

The three enforcement paths

graph LR
    A["Twig form (Storefront)"] --> D["Form validation"]
    B["Route (login / checkout / Shop API)"] --> E["Route check on kernel.request"]
    C["Plugin event (support form, newsletter)"] --> F["Event listener"]
    D --> G["Submission guard chain"]
    E --> G
    F --> G
    G --> H["Channel settings"]

A form rejection is added as a form error and also flashed, because Sylius' shop templates render fields individually and never a form's own errors.

Plugin structure

src/
├── Challenge/          # Challenge generation and signing
├── Command/            # SetupCommand, PurgeCommand, UpdateDisposableDomainsCommand
├── Controller/         # ChallengeController, BlockedDomainsController
├── DependencyInjection/
├── DisposableEmail/    # Disposable-mail guard, domain list, override entities
├── Enforcement/        # Form type extension, route listener, event listener/registrar
├── Entity/             # ChannelSettings, CustomTarget, DisposableDomainOverride, GibberishLogEntry, RateLimitHit, UsedChallenge
├── Form/Type/          # Admin form types
├── Gibberish/          # Scorer, trigram tables, build script
├── Guard/              # SubmissionGuard orchestrating all checks, Rejection enum
├── Menu/               # Admin sidebar entry
├── Migrations/         # Seven Doctrine migrations
├── RateLimit/          # Rate limiter
├── Request/
├── Security/           # Secret cipher (libsodium)
├── Settings/           # Channel settings provider/factory
├── Submission/
├── Target/             # ProtectionTarget, registry, built-in targets
├── Twig/               # mmd_altcha_widget() function
├── Validator/
└── Verification/       # Proof verification and replay guard
config/
├── grids/              # Four admin grids
├── routes/             # admin.yaml, shop.yaml
└── twig_hooks/         # admin.yaml (title-block and action hooks in the admin), shop.yaml (storefront widget hooks, incl. mmd_altcha.widget*)

Entities

ChannelSettings, CustomTarget, DisposableDomainOverride, GibberishLogEntry, RateLimitHit and UsedChallenge: six tables named mmd_sylius_altcha_*. There are seven migrations:

• The first creates two tables (used_challenge and rate_limit_hit).
• The second creates channel_settings, the third custom_target.
• The fourth adds the disposable-mail switch to channel_settings and creates disposable_domain_override.
• The fifth only adds the gibberish-check columns to channel_settings.
• The sixth creates gibberish_log.
• The seventh only adds the challenge endpoint's call limit to channel_settings.

Operating notes

• Client address. Rate limits are per form and client. IPv6 clients are counted per /64. Behind a reverse proxy or CDN, set Symfony's framework.trusted_proxies (and trusted_headers), or every visitor shares one bucket and a burst from a single person locks the form for everybody.
• Checkout sign-in. The returning-customer login inside the checkout (sylius_shop_json_login_check) posts through its own JavaScript, which cannot carry a proof. It is therefore only rate limited (target checkout_login), never asked for a proof. The limit counts every attempt, successful ones included, and is shared by everyone behind one IPv4 address: for customers behind a carrier-grade NAT or an office address, raise the rate limit or untick the target.
• Newsletter checkbox. The newsletter signup that piggybacks on the registration form's checkbox is not checked a second time, because registration has its own check. The public signup forms and the API are checked.
• Two targets, one event. Only one target enforces a given event (the first one registered). A second target declaring the same event is ignored with a warning, because both would check the same submission and the second would find the proof already consumed.
• Live Components. The registration form is a Live Component that re-validates on every field change. Those re-renders are not checked. A custom LiveAction that really submits a protected form is checked and must send the proof (X-Altcha-Payload header or an altcha field).
• Logging. When the database cannot answer (for example before the migration ran), forms run unprotected rather than failing. A warning is logged each time.