nodebb-plugin-geetest

Geetest v4 (极验第四代) captcha plugin for NodeBB forum software.

Features

• Integrates Geetest v4 captcha into NodeBB registration process
• Supports latest NodeBB v3.x+
• Modern async/await code patterns
• Multi-language support (English, German, Chinese)
• Admin settings panel for easy configuration

Installation

1. Install the plugin via npm:

   npm install nodebb-plugin-geetest

2. Activate the plugin in NodeBB Admin Control Panel (ACP):

   • Navigate to Manage > Plugins
   • Find "Geetest v4 Captcha" and click Install

3. Configure the plugin:

   • Go to Manage > Plugins > Geetest v4 Settings
   • Enable the captcha
   • Enter your Geetest Captcha ID and Captcha Key
   • Save settings and reload NodeBB

Configuration

Getting Geetest Credentials

1. Register an account at Geetest
2. Create a new captcha application
3. Get your Captcha ID and Captcha Key from the dashboard

Plugin Settings

• Enable Geetest v4 Captcha: Toggle to enable/disable captcha verification
• Captcha ID: Your Geetest captcha ID (public key)
• Captcha Key: Your Geetest captcha key (secret key)

Technical Details

Backend Validation

The plugin validates captcha responses using Geetest v4's server-side API:

• Endpoint: http://gcaptcha4.geetest.com/validate
• Uses HMAC-SHA256 signature for secure validation
• Validates lot_number, captcha_output, pass_token, and gen_time

Frontend Integration

• Loads Geetest v4 SDK from https://static.geetest.com/v4/gt4.js
• Uses initGeetest4 for initialization
• Product type: bind (seamless integration)
• Automatically appends validation tokens to registration form

Hooks Used

• static:app.load: Initialize plugin and load settings
• filter:admin.header.build: Add admin navigation
• filter:register.build: Add captcha to registration form
• filter:register.check: Validate captcha on form submission

Requirements

• NodeBB v3.0.0 or higher
• Node.js 14 or higher
• axios (automatically installed as dependency)

Troubleshooting

Captcha not showing

1. Check if the plugin is activated in ACP
2. Verify that captcha is enabled in settings
3. Ensure Captcha ID and Key are correctly entered
4. Check browser console for JavaScript errors

Validation failed

1. Verify your Geetest credentials are correct
2. Check server connectivity to gcaptcha4.geetest.com
3. Ensure server time is synchronized (NTP)
4. Check NodeBB logs for detailed error messages

Development

Local Testing

1. Clone your NodeBB instance
2. Link the plugin:

   cd nodebb-plugin-geetest
   npm link
   cd ../NodeBB
   npm link nodebb-plugin-geetest
   ./nodebb build
   ./nodebb dev

File Structure

nodebb-plugin-geetest/
├── languages/           # Translation files
│   ├── de/             # German
│   ├── en-GB/          # English
├── public/
│   ├── js/
│   │   └── main.js     # Frontend captcha logic
│   └── templates/
│       └── admin/
│           └── plugins/
│               └── geetest.tpl  # Admin settings
├── library.js           # Main plugin logic
├── plugin.json          # Plugin configuration
└── package.json         # Dependencies

License

MIT License

Support

For issues and feature requests, please open an issue on the GitHub repository.

Changelog

v1.0.0

• Complete rewrite for NodeBB v3.x compatibility
• Upgraded to Geetest v4 API
• Modern async/await patterns
• Improved error handling
• Enhanced security with HMAC-SHA256 validation
• Multi-language support