How to push a PR to add support for ALTCHA (on premise) #151

Activity

1. lctwo

   changed the title [-]Support for self-hosted ALTCHA CAPTCHA provider (PR guidance)[/-] [+]How to make a PR to give my support for ALTCHA (on premise)[/+] on Aug 1, 2026
2. lctwo

   changed the title [-]How to make a PR to give my support for ALTCHA (on premise)[/-] [+]How to push a PR to add support for ALTCHA (on premise)[/+] on Aug 1, 2026
3. sabban commented on Sep 1, 2026

   

   sabban

   on Sep 1, 2026

   Contributor

   More actions

   └ Hi @clionelc,

   Thanks for the proposal. ALTCHA support sounds like a good fit here, especially for self-hosted / no external CAPTCHA dependency setups.
   For the repository split, I would structure it like this:
   - lua-cs-bouncer: keep the generic provider support here. That includes the Lua implementation (captcha.lua changes and the altcha.lua helper), the ALTCHA captcha template, config example updates, and tests.
   - cs-nginx-bouncer: keep nginx packaging/integration snippets here. If ALTCHA needs additional nginx location blocks such as /altcha-challenge and /altcha.js, those should go in the nginx bouncer repo as a clear optional example, probably next to nginx/crowdsec_nginx.conf, rather than something enabled automatically by the default install flow.
   - cs-openresty-bouncer: please keep this in line with the nginx bouncer as well. The lua library is shared by both projects, so any optional nginx-side example, template path, or documentation change needed for ALTCHA should have the equivalent OpenResty change or at least be called out in the PR.

   So I would suggest opening the first PR against crowdsecurity/lua-cs-bouncer with the provider support itself. If that PR needs nginx snippet changes to show how ALTCHA should be wired in a vhost, open a second PR against crowdsecurity/cs-nginx-bouncer with that as a optional example (maybe in a separate file), and check whether the same example is needed in crowdsecurity/cs-openresty-bouncer. Please link the related PRs together.

   Before opening the PR, please include:
   - an update to config_example.conf, changing the provider comment from recaptcha, hcaptcha, turnstile to include altcha;
   - a test under t/ covering the ALTCHA provider path. The existing captcha tests (t/13_stream_captcha_and_deletion.t and t/14_stream_captcha_and_cache.t) are good examples of the
   style;
   - if possible, a validation test for both challenge generation and proof verification without requiring network access;
   - a short note in the PR description explaining whether altcha.min.js is vendored, where it comes from, and which upstream version / license it corresponds to.

   The current CI installs dependencies and runs the Perl nginx test suite with:

   export PERL5LIB=/root/.cpan/build/Test-Nginx-0.30-3/blib/lib
   for i in t/*.t; do
        prove "$i"
   done

   Locally, the same tests require nginx with the Lua module, lua-cjson, lua-resty-http, Test::Nginx, and Test::Nginx::Socket. If you cannot run the whole suite locally, please mention that in the PR description and include the exact setup where you tested it manually.

   Two implementation points to watch for:
   - ALTCHA should not make the existing cloud CAPTCHA providers regress. Keeping provider-specific code isolated, for example in plugins/crowdsec/altcha.lua, is preferable to making
   captcha.lua too branch-heavy.
   - If SITE_KEY is not actually needed by ALTCHA, it would be better not to require a fake value long term. If changing that is too invasive for the first PR, mention it explicitly so we
   can decide whether to accept the compatibility placeholder or adjust config validation.

   Regards,
4. lctwo commented on Sep 4, 2026

   

   lctwo

   on Sep 4, 2026

   Last edited by lctwo

   Author

   More actions

   Hi,

   Thanks for the answer and the guidance. I don't really understand how to create the "t/" file, so I'll go ahead and make the PR as is — perhaps someone else could complete it afterwards.

   When all will be ok i will push also a pr in crowdsecurity/cs-openresty-bouncer

   #156
5. lctwo

   closed this as completedon Sep 4, 2026