Skip to content

Security: add hCaptcha validation for generating docx#35

Merged
GTPSHAX merged 10 commits into
NgodingCik:mainfrom
GTPSHAX:security
May 4, 2026
Merged

Security: add hCaptcha validation for generating docx#35
GTPSHAX merged 10 commits into
NgodingCik:mainfrom
GTPSHAX:security

Conversation

@GTPSHAX
Copy link
Copy Markdown
Contributor

@GTPSHAX GTPSHAX commented May 4, 2026

Summary

This PR introduces hCaptcha integration across the application to enhance security, specifically targeting the document generation process. By implementing both frontend widgets and backend verification, the system now effectively mitigates automated bot abuse and protects resource-intensive generation tasks.

Key Changes

  • hCaptcha Integration: Added HCAPTCHA_SECRET_KEY and HCAPTCHA_SITE_KEY across all environment schemas. The hCaptcha widget and necessary scripts have been integrated into the document generation form in home.ejs.
  • Dynamic Metadata: Updated apps/web routes to pass the site key via a META object, ensuring the frontend can initialize the widget dynamically based on environment settings.
  • Security Policy Updates: Refactored Content Security Policy (CSP) headers in the Helmet middleware to whitelist hCaptcha domains for scripts, styles, frames, and connect-src.
  • Backend Validation: Implemented a dedicated server-side validation handler using the hcaptcha npm package. This validation is now a required step in the handle-generate-docx.js workflow.

Why this is necessary

Preventing automated bot traffic is critical for maintaining service stability and controlling costs associated with document generation. This implementation:

  1. Reduces Spam: Ensures that only human users can trigger document generation tasks.
  2. Improves Security: Updates CSP headers to maintain a "Secure by Default" posture while allowing third-party security tools.
  3. Standardizes Config: Centralizes captcha keys in environment variables for easier management across different deployment environments (Dev/Staging/Prod).

How to Test

  1. Configuration: Add your hCaptcha keys to the .env file (HCAPTCHA_SITE_KEY and HCAPTCHA_SECRET_KEY).
  2. Frontend Render: Navigate to the document generation page and verify the hCaptcha widget appears before the submit button.
  3. Verification Flow: Attempt to generate a document without completing the captcha; it should fail. Complete the captcha and verify that the backend successfully validates the token and processes the request.
  4. CSP Check: Open the browser console to ensure there are no "Content Security Policy" violations related to hcaptcha.com.

Attachment Reference:
hCaptcha Integration Evidence
The provided screenshot confirms the environment variable additions and the logic updates in the backend handlers.

@GTPSHAX GTPSHAX self-assigned this May 4, 2026
@GTPSHAX GTPSHAX added documentation Improvements or additions to documentation enhancement New feature or request labels May 4, 2026
@GTPSHAX GTPSHAX marked this pull request as ready for review May 4, 2026 19:48
@GTPSHAX GTPSHAX merged commit 8a0ada9 into NgodingCik:main May 4, 2026
1 check passed
@GTPSHAX GTPSHAX deleted the security branch May 4, 2026 19:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant