Add information about the anti-spam module

astro.config.mjs

@@ -56,6 +56,10 @@ export default defineConfig({
               label: 'Email Templates',
               slug: 'admin-guide/email-templates',
             },
+            {
+              label: 'Anti-Spam',
+              slug: 'admin-guide/anti-spam',
+            },
             {
               label: 'Localization',
               slug: 'admin-guide/localization',

src/content/docs/admin-guide/anti-spam.mdoc

@@ -0,0 +1,120 @@
+---
+title: The Anti-Spam Module
+description: Configure FOSSBilling's anti-spam module to reduce abusive registrations, public tickets, and login attempts.
+---
+
+The Anti-Spam module helps reduce automated abuse by combining CAPTCHA checks, IP blocking, disposable email detection, Stop Forum Spam lookups, and a hidden signup honeypot field.
+
+Use these protections together. CAPTCHA and honeypot checks help block automated signups, while IP and email checks help block repeated abusive traffic.
+
+## What It Protects
+
+Anti-spam checks run before several public and client actions:
+
+| Protection | Applies To |
+|------------|------------|
+| IP blocking | Client signup, public ticket opening, client profile updates, client login, admin login |
+| CAPTCHA | Client signup and public ticket opening |
+| Stop Forum Spam | Client signup and public ticket opening |
+| Disposable email detection | Client signup and public ticket opening |
+| Honeypot | Client signup |
+
+## IP Blocking
+
+Enable **IP Blocking** to reject requests from known abusive IP addresses.
+
+Add one IP address per line in the blocked IP list:
+
+```text
+203.0.113.10
+2001:db8::10
+```
+
+Blocked IP addresses cannot log in, register, update client details, or open public tickets.
+
+## CAPTCHA Protection
+
+Enable **CAPTCHA** to require visitors to complete a verification challenge before submitting protected public forms.
+
+FOSSBilling supports these providers:
+
+| Provider | Required Settings | Notes |
+|----------|-------------------|-------|
+| Google reCAPTCHA v2 | Site key, secret key | Shows a visible reCAPTCHA challenge |
+| Google reCAPTCHA v3 | Site key, secret key, minimum score | Uses a score from `0.0` to `1.0`; higher thresholds are stricter |
+| Cloudflare Turnstile | Site key, secret key | Uses Cloudflare's CAPTCHA alternative |
+| hCaptcha | Site key, secret key | Uses hCaptcha verification |
+
+Get provider keys from the provider's dashboard:
+
+- [Google reCAPTCHA](https://www.google.com/recaptcha/about/)
+- [Cloudflare Turnstile](https://www.cloudflare.com/products/turnstile/)
+- [hCaptcha](https://www.hcaptcha.com/)
+
+### reCAPTCHA v3 Score
+
+For reCAPTCHA v3, FOSSBilling compares Google's score with the configured minimum score. The default is `0.5`.
+
+- Lower values allow more submissions but may let more spam through
+- Higher values block more suspicious submissions but may reject legitimate users
+- Keep the value between `0.0` and `1.0`
+
+## Stop Forum Spam
+
+Enable **Stop Forum Spam** to check submitted IP and email details against the [Stop Forum Spam](https://stopforumspam.com/) database before signup or public ticket creation.
+
+If Stop Forum Spam reports a submitted username, email address, or IP address as abusive, FOSSBilling rejects the request.
+
+{% aside type="note" %}
+This feature depends on the external Stop Forum Spam API. If the service is unavailable or returns an unsuccessful response, FOSSBilling does not block the request based on that lookup alone.
+{% /aside %}
+
+## Disposable Email Protection
+
+Enable **Disposable Email Protection** to reject email addresses from temporary or throwaway email domains.
+
+FOSSBilling downloads the disposable domain list from the [FakeFilter](https://github.com/7c/fakefilter) project and caches it for 24 hours. If the list cannot be downloaded, FOSSBilling retries later and does not block addresses from an empty list.
+
+## Honeypot Protection
+
+Enable **Honeypot Protection** to add a hidden field to the signup form. Most people never fill this field, but simple bots often do.
+
+The default honeypot field name is `bio`. If the field is submitted with a value, FOSSBilling rejects the registration and records an informational log entry.
+
+Change the field name if you suspect bots are learning to ignore the default field.
+
+## Recommended Setup
+
+For most production installations:
+
+1. Enable a CAPTCHA provider and confirm the site key and secret key are correct
+2. Keep disposable email protection enabled
+3. Keep honeypot protection enabled
+4. Enable Stop Forum Spam and make sure your server can make outbound requests to `stopforumspam.com`
+5. Use IP blocking for repeat offenders, not as the only spam control
+
+## Troubleshooting
+
+### CAPTCHA Always Fails
+
+- Check that the selected provider matches the keys you entered
+- Verify that the site key is allowed for your billing domain in the provider dashboard
+- Confirm your server can make outbound HTTPS requests to the provider verification endpoint
+- For reCAPTCHA v3, try lowering the minimum score if legitimate users are being rejected
+
+### Legitimate Email Addresses Are Blocked
+
+- Disable disposable email protection temporarily to confirm whether it is the cause
+- Ask the user for a non-disposable email address
+- Check whether the domain appears in the FakeFilter list
+
+### Users Are Blocked by IP Address
+
+- Review the blocked IP list and remove stale entries
+- If FOSSBilling is behind a reverse proxy, configure trusted proxies correctly so FOSSBilling sees the real visitor IP. See [Configuration File](/admin-guide/config/#trusted-proxies).
+
+### Signups Fail Without a Visible CAPTCHA Error
+
+- Check whether honeypot protection is enabled
+- Review logs for the message `Potential spam registration blocked`
+- Change the honeypot field name if bots are targeting the default field

src/content/docs/admin-guide/index.mdoc

@@ -26,6 +26,11 @@ Start with [Configuration](/admin-guide/config/) and [Company Information](/admi
     href="/admin-guide/email-templates/"
     description="Customize the messages FOSSBilling sends to clients and staff."
   /%}
+  {% linkcard
+    title="Anti-Spam"
+    href="/admin-guide/anti-spam/"
+    description="Reduce abusive signups, public tickets, and login attempts."
+  /%}
   {% linkcard
     title="Localization"
     href="/admin-guide/localization/"

src/content/docs/extensions-and-development/guides/creating-a-theme.mdoc

@@ -142,6 +142,7 @@ Custom layouts that do not extend the bundled themes should load the shared runt
 - Validate all inputs
 - Use `fb_api_form` and `fb_api_link` for browser API actions
 - Include CSRF tokens manually for raw requests that do not use the wrapper
+- Include the [antispam honeypot](/admin-guide/anti-spam/#honeypot-protection) field in custom signup or public submission forms
 - See the [security docs](/security/securing-fossbilling) for more
 
 ## Testing Your Theme

src/content/docs/extensions-and-development/twig-filters.mdoc

@@ -73,7 +73,7 @@ Project-specific filters and functions are defined in these classes:
 | `render_widgets` | Render widgets registered for a slot. |
 | `svg_sprite` | Render the current theme's SVG icon sprite when available. |
 | `has_permission` | Check whether the logged-in admin has a module permission. |
-| `antispam_honeypot` | Return the antispam honeypot configuration array. |
+| `antispam_honeypot` | Return the [antispam honeypot](/admin-guide/anti-spam/#honeypot-protection) configuration array. |
 | `wysiwyg` | Load and initialize the shared CKEditor bundle for a selector. |
 
 ## Usage Examples

src/content/docs/maintenance/Updating/0-7-to-0-8.mdoc

@@ -38,10 +38,10 @@ The following modules have been removed or replaced. The patcher handles the mig
 | Change | Details |
 |--------|---------|
 | `Servicemembership` removed | Membership products and orders are migrated to the "custom" product type. Review active membership orders after updating. |
-| `Spamchecker` replaced | Replaced by the new `Antispam` module (supports Cloudflare Turnstile, hCaptcha, and honeypot fields). Review your spam-protection settings after the update. |
+| `Spamchecker` replaced | Replaced by the new [`Antispam`](/admin-guide/anti-spam/) module (supports Cloudflare Turnstile, hCaptcha, and honeypot fields). Review your spam-protection settings after the update. |
 | `Wysiwyg` removed | CKEditor 5 is now integrated directly into themes. Use the `wysiwyg` Twig function to initialize editors. |
 | `Paidsupport` removed | Module data is cleaned up. |
-| Added `Antispam` | New spam-prevention module with multiple challenge providers. |
+| Added `Antispam` | New [spam-prevention module](/admin-guide/anti-spam/) with multiple challenge providers. |
 | Added `Widgets` | New module for registering renderable widget slots in templates. |
 
 ## Uploads Directory
@@ -361,7 +361,7 @@ Gravatar has been removed. User avatars are now generated locally using DiceBear
 
 ## Honeypot Enabled by Default
 
-The new Antispam module enables honeypot spam prevention by default for supported forms such as signup. If you have custom signup or public submission forms, use the `antispam_honeypot` function to include honeypot fields:
+The new [Antispam module](/admin-guide/anti-spam/) enables honeypot spam prevention by default for supported forms such as signup. If you have custom signup or public submission forms, use the `antispam_honeypot` function to include honeypot fields:
 
 ```twig
 {\% set honeypot = antispam_honeypot() %}

src/content/docs/security/securing-fossbilling.mdoc

@@ -89,7 +89,7 @@ Rate limiting is configured under the `rate_limiter` block, replacing the old `a
 
 ## Antispam
 
-The `Antispam` module (replaces the old `Spamchecker` module) provides built-in spam protection including honeypot fields. Configure it under **Extensions → Antispam**.
+The `Antispam` module (replaces the old `Spamchecker` module) provides built-in spam protection including CAPTCHA, IP blocking, disposable email detection, Stop Forum Spam lookups, and honeypot fields. See [Anti-Spam](/admin-guide/anti-spam/) for setup and troubleshooting.
 
 ## Cloudflare
 
@@ -99,4 +99,4 @@ If you're using Cloudflare, enable **IP Geolocation** under your site's **Networ
 
 ### HTTPS Detection
 
-Reverse proxies often make FOSSBilling think it is being accessed over HTTP even when the visitor is using HTTPS. To avoid that, make sure your proxy forwards `X-Forwarded-Proto: https`.
+Reverse proxies often make FOSSBilling think it is being accessed over HTTP even when the visitor is using HTTPS. To avoid that, make sure your proxy forwards `X-Forwarded-Proto: https`.

src/content/docs/support/features.mdoc

@@ -18,7 +18,7 @@ Use this page as a quick reference for what is available today, what is in progr
 
 ## Security & Anti-Spam
 
-The `Antispam` module (replaces the old `Spamchecker` module in 0.8.0) provides built-in spam protection. Configure it under **Extensions → Antispam**.
+The `Antispam` module (replaces the old `Spamchecker` module in 0.8.0) provides built-in spam protection. See [Anti-Spam](/admin-guide/anti-spam/) for configuration details.
 
 | Feature | Status | Notes |
 |---------|--------|-------|