Release v1.2.0 - ALTCHA proof-of-work bot protection

Replaces per-IP rate limiting (which broke for organisations with many
users behind one NAT IP) with a per-browser SHA-256 proof-of-work
challenge solved in a Web Worker. Cost is paid per browser, the
challenge is invisible to legitimate users, no third-party service or
external JS is involved, and difficulty adapts to per-form submit rate.

The challenge signature is bound to the form's file ID so a challenge
issued for one form cannot be reused on another. Single-use replay
protection via Nextcloud's distributed cache (Redis) with APCu fallback
for single-server installs.

The anonymous submit rate limit becomes a generous safety net (raised
from 100/hour to 25 000/hour) so that even a 10 000-employee training
evaluation finishing within one hour goes through, while pathological
abuse is still bounded if the cache backend goes down.

Closes #76. Also includes the markdown-rendering fix for public form
descriptions from #63 (h1/lists/links/etc. now render correctly with
explicit typography styles that survive Nextcloud's CSS resets).

Also fixes #77: authenticated submit failed for restricted folders.
When a public form had `require_login: true` and lived in a Group
Folder or Team Folder the respondent wasn't a member of, the
authenticated submit path called formService->load() — a user-context
loader that requires folder ACL — and failed with "Form not found".
submitAuthenticated() now uses loadPublic() (the same admin-bypass
loader anonymous submissions use); auth gates (token, share gate,
allowed_users/groups, require_login) still run before it, so there
is no change in authorization scope, only the read handle for the
form definition.

Author: Rikdekker

CHANGELOG.md

@@ -2,10 +2,17 @@
 
 All notable changes to FormVox will be documented in this file.
 
-## [1.1.6] - 2026-05-05
+## [1.2.0] - 2026-05-05
+
+### Added
+- **Bot protection that works behind NAT** — Public form submissions are now protected by an ALTCHA-style proof-of-work challenge solved in the user's browser, replacing per-IP rate limiting as the primary anti-bot defense. Cost is paid per browser, so an organisation with hundreds of users behind a single NAT IP all submit without throttling. The challenge is invisible to legitimate users (~50–150 ms of work in a Web Worker), self-hosted (no third-party service, no external JS, no API keys, GDPR-clean), and adapts difficulty to the per-form submit rate so attackers pay more under load. The signature is bound to the form's file ID so a challenge issued for one form cannot be reused on another. Single-use replay protection via Nextcloud's distributed cache (Redis) with APCu fallback for single-server installs. ([#76](https://github.com/nextcloud/formvox/issues/76))
+
+### Changed
+- **Anonymous submit rate limit raised from 100/hour to 25 000/hour** — With ALTCHA now the primary defense, the per-IP limit becomes a wide safety net rather than the front line. The new ceiling comfortably accommodates large-organisation peaks (think 10 000 employees filling in a training evaluation in one hour) while still bounding pathological abuse if the cache backend goes down.
 
 ### Fixed
 - **Form description rendered as plain text on the public form** — The form description on the public response page now renders as markdown instead of literal text with the raw `#`/`*` characters and collapsed newlines. Headings, lists, links, code, and blockquotes in the form description, section descriptions, and the in-editor markdown preview all render with proper visual styling. ([#63](https://github.com/nextcloud/formvox/issues/63))
+- **"Form not found" / "Access forbidden" for logged-in respondents on restricted folders** — When a public form had `require login` enabled and was stored in a Group Folder or Team Folder the respondent was not a member of, the submission failed because the authenticated submit path used a user-context file load. Authenticated respondents now use the same admin-bypass loader as anonymous submissions, so the share link plus token (and any `allowed_users`/`allowed_groups` rules) are the only gate — no folder ACL needed. ([#77](https://github.com/nextcloud/formvox/issues/77))
 
 ## [1.1.5] - 2026-05-04
 

appinfo/info.xml

@@ -35,7 +35,7 @@
 * Expense declarations
 * Data collection with privacy requirements
     ]]></description>
-    <version>1.1.6</version>
+    <version>1.2.0</version>
     <licence>agpl</licence>
     <author mail="info@voxcommons.com">Sam Ditmeijer</author>
     <author mail="info@voxcommons.com">Rik Dekker</author>

appinfo/routes.php

@@ -13,6 +13,7 @@
         ['name' => 'public#showForm', 'url' => '/public/{fileId}/{token}', 'verb' => 'GET'],
         ['name' => 'public#authenticate', 'url' => '/public/{fileId}/{token}', 'verb' => 'POST'],
         ['name' => 'public#submit', 'url' => '/public/{fileId}/{token}/submit', 'verb' => 'POST'],
+        ['name' => 'public#challenge', 'url' => '/public/{fileId}/{token}/challenge', 'verb' => 'GET'],
         ['name' => 'public#uploadFile', 'url' => '/public/{fileId}/{token}/upload', 'verb' => 'POST'],
 
         // Embed routes (frameable version for iframes)

js/da0651ca5ec18ccbe5fd.js

@@ -25,6 +25,7 @@
 use OCA\FormVox\Service\FormService;
 use OCA\FormVox\Service\ResponseService;
 use OCA\FormVox\Service\BrandingService;
+use OCA\FormVox\Service\ChallengeService;
 
 class PublicController extends Controller
 {
@@ -35,6 +36,7 @@ class PublicController extends Controller
     private FormService $formService;
     private ResponseService $responseService;
     private BrandingService $brandingService;
+    private ChallengeService $challengeService;
     private IInitialState $initialState;
 
     public function __construct(
@@ -46,6 +48,7 @@ public function __construct(
         FormService $formService,
         ResponseService $responseService,
         BrandingService $brandingService,
+        ChallengeService $challengeService,
         IInitialState $initialState
     ) {
         parent::__construct(Application::APP_ID, $request);
@@ -56,6 +59,7 @@ public function __construct(
         $this->formService = $formService;
         $this->responseService = $responseService;
         $this->brandingService = $brandingService;
+        $this->challengeService = $challengeService;
         $this->initialState = $initialState;
     }
 
@@ -337,15 +341,46 @@ private function getEffectiveBranding(array $form): array
         return $this->brandingService->getBranding();
     }
 
+    /**
+     * Issue an ALTCHA proof-of-work challenge for a public form.
+     *
+     * Replaces per-IP rate limiting on submit (NAT-unfriendly) with a
+     * per-browser PoW token. Difficulty adapts to the per-form submit rate.
+     */
+    #[PublicPage]
+    #[NoCSRFRequired]
+    public function challenge(int $fileId, string $token): DataResponse
+    {
+        // $token is required for route binding (so /public/{fileId}/challenge
+        // doesn't collide with /public/{fileId}/{token}); we don't validate
+        // it here — verification happens at submit time.
+        unset($token);
+        return new DataResponse($this->challengeService->issue($fileId));
+    }
+
     /**
      * Submit response (anonymous or authenticated based on form settings)
      */
     #[PublicPage]
     #[NoCSRFRequired]
-    #[AnonRateLimit(limit: 100, period: 3600)]
+    #[AnonRateLimit(limit: 25000, period: 3600)]
     #[BruteForceProtection(action: 'formvox_submit')]
-    public function submit(int $fileId, string $token, array $answers): DataResponse
+    public function submit(int $fileId, string $token, array $answers, ?array $altcha = null): DataResponse
     {
+        // Anti-bot: require a valid ALTCHA proof-of-work token before doing
+        // any work. Cost is per-browser, so 500 users behind one NAT IP each
+        // pay their own (tiny) cost — see issue #76. The AnonRateLimit above
+        // remains as a generous safety net for pathological cases.
+        if ($this->userSession->getUser() === null
+            && !$this->challengeService->verify($altcha, $fileId)) {
+            $response = new DataResponse(
+                ['error' => 'Challenge verification failed. Please refresh the page.'],
+                Http::STATUS_TOO_MANY_REQUESTS
+            );
+            $response->throttle();
+            return $response;
+        }
+
         try {
             $form = $this->loadAndValidateForm($fileId, $token);
 

js/formvox-public.js

@@ -0,0 +1,196 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OCA\FormVox\Service;
+
+use OCP\IConfig;
+use OCP\ICacheFactory;
+use OCP\Security\ISecureRandom;
+
+/**
+ * ALTCHA-compatible proof-of-work challenge issuer/verifier.
+ *
+ * The browser solves SHA-256(salt + N) for some N in [0, maxnumber] such that
+ * the digest matches the expected `challenge`. Difficulty = expected work,
+ * tuned by maxnumber. Server-side verification recomputes the digest, checks
+ * the HMAC signature (so the client can't forge a challenge), and enforces
+ * single-use via cache to prevent replay.
+ *
+ * Replaces per-IP rate limiting on public form submission — cost is per
+ * browser, NAT-friendly. See issue #76.
+ */
+class ChallengeService
+{
+    /** Single-use challenge expiry, in seconds. */
+    private const EXPIRY_SECONDS = 600;
+
+    /** Difficulty rungs (max number to search). Higher = more work. */
+    private const DIFFICULTY_LOW = 50_000;
+    private const DIFFICULTY_MID = 250_000;
+    private const DIFFICULTY_HIGH = 1_000_000;
+
+    /** Submit-rate thresholds (per hour, per form) that bump difficulty. */
+    private const RATE_THRESHOLD_MID = 1_500;
+    private const RATE_THRESHOLD_HIGH = 10_000;
+
+    public function __construct(
+        private IConfig $config,
+        private ICacheFactory $cacheFactory,
+        private ISecureRandom $secureRandom,
+    ) {
+    }
+
+    /**
+     * Cache for replay-protection and rate tracking.
+     *
+     * Prefers a distributed backend (Redis/Memcached) for multi-server
+     * setups; falls back to the local backend (APCu) which works fine for
+     * the ~95% of Nextcloud installs that run on a single server. If
+     * neither is available we return null and the caller treats that as
+     * "challenge accepted, no replay tracking" — better than refusing all
+     * submissions on a misconfigured instance.
+     */
+    private function cache(): ?\OCP\ICache
+    {
+        if ($this->cacheFactory->isAvailable()) {
+            return $this->cacheFactory->createDistributed('formvox_altcha_');
+        }
+        if ($this->cacheFactory->isLocalCacheAvailable()) {
+            return $this->cacheFactory->createLocal('formvox_altcha_');
+        }
+        return null;
+    }
+
+    /**
+     * Issue a new challenge for a given form.
+     *
+     * Difficulty adapts to the per-form submit rate so a popular form does
+     * not penalise other forms on the same instance.
+     *
+     * @return array{algorithm:string,challenge:string,salt:string,signature:string,maxnumber:int}
+     */
+    public function issue(int $fileId): array
+    {
+        $maxnumber = $this->currentDifficulty($fileId);
+        $secretNumber = random_int(0, $maxnumber);
+        $salt = bin2hex(random_bytes(12));
+        $challenge = hash('sha256', $salt . $secretNumber);
+        // Bind the signature to the fileId so a challenge issued for a
+        // low-difficulty form can't be reused on a high-difficulty form
+        // (which would defeat adaptive difficulty escalation).
+        $signature = hash_hmac('sha256', $fileId . ':' . $challenge, $this->hmacKey());
+
+        return [
+            'algorithm' => 'SHA-256',
+            'challenge' => $challenge,
+            'salt' => $salt,
+            'signature' => $signature,
+            'maxnumber' => $maxnumber,
+        ];
+    }
+
+    /**
+     * Verify a solved challenge payload from the client.
+     *
+     * Expected payload shape (ALTCHA standard):
+     *   { algorithm, challenge, salt, signature, number }
+     */
+    public function verify(?array $payload, int $fileId): bool
+    {
+        if (!\is_array($payload)) {
+            return false;
+        }
+        foreach (['algorithm', 'challenge', 'salt', 'signature', 'number'] as $k) {
+            if (!isset($payload[$k])) {
+                return false;
+            }
+        }
+        if ($payload['algorithm'] !== 'SHA-256') {
+            return false;
+        }
+
+        // Signature is bound to fileId — see issue(). A challenge issued for
+        // form A will not validate when submitted to form B.
+        $expectedSig = hash_hmac('sha256', $fileId . ':' . (string)$payload['challenge'], $this->hmacKey());
+        if (!hash_equals($expectedSig, (string)$payload['signature'])) {
+            return false;
+        }
+
+        $recomputed = hash('sha256', $payload['salt'] . $payload['number']);
+        if (!hash_equals($recomputed, (string)$payload['challenge'])) {
+            return false;
+        }
+
+        // Single-use: reject if we've seen this challenge before.
+        // If no cache backend is available we accept the challenge (HMAC +
+        // SHA-256 still verified above) but lose replay protection — better
+        // than blocking all submissions on a misconfigured instance.
+        $cache = $this->cache();
+        if ($cache !== null) {
+            $key = "used_{$fileId}_" . substr($payload['challenge'], 0, 32);
+            if ($cache->get($key)) {
+                return false;
+            }
+            $cache->set($key, 1, self::EXPIRY_SECONDS);
+        }
+
+        // Track per-form submit rate so difficulty adapts on the next issue().
+        $this->bumpSubmitRate($fileId);
+
+        return true;
+    }
+
+    private function currentDifficulty(int $fileId): int
+    {
+        $rate = $this->currentSubmitRate($fileId);
+        if ($rate >= self::RATE_THRESHOLD_HIGH) {
+            return self::DIFFICULTY_HIGH;
+        }
+        if ($rate >= self::RATE_THRESHOLD_MID) {
+            return self::DIFFICULTY_MID;
+        }
+        return self::DIFFICULTY_LOW;
+    }
+
+    private function currentSubmitRate(int $fileId): int
+    {
+        $cache = $this->cache();
+        if ($cache === null) {
+            return 0;
+        }
+        return (int)($cache->get($this->rateKey($fileId)) ?? 0);
+    }
+
+    private function bumpSubmitRate(int $fileId): void
+    {
+        $cache = $this->cache();
+        if ($cache === null) {
+            return;
+        }
+        $cache->set($this->rateKey($fileId), $this->currentSubmitRate($fileId) + 1, 3600);
+    }
+
+    private function rateKey(int $fileId): string
+    {
+        return "submit_rate_{$fileId}_" . $this->currentHourBucket();
+    }
+
+    private function currentHourBucket(): string
+    {
+        return (string)((int)floor(time() / 3600));
+    }
+
+    private function hmacKey(): string
+    {
+        $secret = $this->config->getSystemValueString('secret', '');
+        if ($secret === '') {
+            $secret = $this->config->getAppValue('formvox', 'altcha_hmac_key', '');
+            if ($secret === '') {
+                $secret = $this->secureRandom->generate(64, ISecureRandom::CHAR_ALPHANUMERIC);
+                $this->config->setAppValue('formvox', 'altcha_hmac_key', $secret);
+            }
+        }
+        return 'formvox_altcha:' . $secret;
+    }
+}

lib/Controller/PublicController.php

@@ -94,7 +94,11 @@ public function submitAnonymousWithForm(int $fileId, array $form, array $answers
      */
     public function submitAuthenticated(int $fileId, array $answers, string $userId, string $displayName): array
     {
-        $form = $this->formService->load($fileId);
+        // Use the admin-bypass loader: respondents are authenticated for
+        // identity (the response is attributed to $userId) but they don't
+        // need file/folder permissions on the form file itself. The share
+        // link + token already validated their right to submit. (#77)
+        $form = $this->formService->loadPublic($fileId);
 
         // Check if form accepts responses
         $this->validateFormAcceptsResponses($form);

lib/Service/ChallengeService.php

@@ -1,6 +1,6 @@
 {
   "name": "formvox",
-  "version": "1.1.6",
+  "version": "1.2.0",
   "description": "File-based forms and polls for Nextcloud",
   "scripts": {
     "build": "webpack",
@@ -16,6 +16,7 @@
     "@nextcloud/router": "^3.0.0",
     "@nextcloud/vue": "^9.1.0",
     "@vue/compiler-sfc": "^3.5.22",
+    "altcha-lib": "^1.2.0",
     "chart.js": "^4.5.1",
     "easymde": "^2.21.0",
     "markdown-it": "^14.1.1",