Skip to content

refactor: enhance hCaptcha validation and error handling logic#36

Merged
GTPSHAX merged 3 commits into
NgodingCik:mainfrom
GTPSHAX:dev
May 5, 2026
Merged

refactor: enhance hCaptcha validation and error handling logic#36
GTPSHAX merged 3 commits into
NgodingCik:mainfrom
GTPSHAX:dev

Conversation

@GTPSHAX
Copy link
Copy Markdown
Contributor

@GTPSHAX GTPSHAX commented May 5, 2026

Summary

This PR enhances the hCaptcha validation flow by introducing conditional logic for both the backend and frontend. The primary goal is to make the security layer more robust while maintaining developer experience, ensuring that the application remains functional and flexible in environments where hCaptcha keys might not be configured (such as local development).

Key Changes

  • Graceful Backend Bypass: Updated handleHCaptchaValidation to automatically bypass verification if HCAPTCHA_SECRET_KEY is missing. A warning is logged to the console to ensure visibility without breaking the application flow.
  • Centralized Validation Logic: Moved the existence check for the h-captcha-response token directly into the validation handler. This centralizes error logging and logic, preventing redundant checks in the main controller.
  • Conditional Frontend Rendering: Modified home.ejs to wrap the hCaptcha widget and its external script in a conditional block. The widget now only renders if HCAPTCHA_SITE_KEY is provided in the metadata.
  • Improved Logging: Added specific warning logs for missing keys or missing response tokens to assist in troubleshooting configuration issues.

Why this is necessary

A "hard-coded" requirement for hCaptcha can hinder development and deployment in restricted environments. These changes provide:

  1. Developer Experience: Developers can run the project locally without needing to configure personal hCaptcha keys unless they are specifically testing that feature.
  2. Optimized Performance: By conditionally loading the hCaptcha script, we reduce unnecessary network requests and third-party script execution for users when the feature is disabled.
  3. Code Maintainability: Centralizing the token check within the handler makes the document generation logic cleaner and easier to read.

How to Test

  1. Local Dev (No Keys): Remove HCAPTCHA_SITE_KEY and HCAPTCHA_SECRET_KEY from your .env. Verify that the hCaptcha widget does not appear and that you can still generate documents (check server logs for the "bypass" warning).
  2. Enabled Mode: Add valid keys to your .env. Verify the widget renders, the script loads, and the backend correctly validates the token.
  3. Missing Token Test: With keys enabled, attempt to bypass the frontend widget manually. The backend should log a warning about the missing h-captcha-response and reject the request.

@GTPSHAX GTPSHAX self-assigned this May 5, 2026
@GTPSHAX GTPSHAX added the enhancement New feature or request label May 5, 2026
@GTPSHAX GTPSHAX marked this pull request as ready for review May 5, 2026 18:57
@GTPSHAX GTPSHAX merged commit a328f49 into NgodingCik:main May 5, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant