ArchivesSpace Cloudflare Turnstile Plugin

A plugin for ArchivesSpace that integrates Cloudflare Turnstile to protect the public interface from bots and automated attacks.

Overview

This plugin adds Cloudflare Turnstile verification to your ArchivesSpace public interface. Users will be presented with a Turnstile challenge before accessing the public site, helping to prevent bot traffic and automated attacks while maintaining a user-friendly experience.

Features

• Cloudflare Turnstile Integration - Seamless bot protection using Cloudflare's Turnstile service
• Session-Based Verification - Once verified, users can browse without repeated challenges
• Automatic Redirect - Users are redirected back to their original destination after verification
• Configurable via AppConfig - Configuration through ArchivesSpace's config.rb

Requirements

• ArchivesSpace (tested with public interface)
• Cloudflare Turnstile account with:
  • Site Key (public)
  • Secret Key (private)

Installation

1. Clone or download this repository into your ArchivesSpace plugins directory:

   cd /path/to/archivesspace/plugins
   git clone https://github.com/your-username/archivesspace_cloudflare_plugin.git cloudflare

   Or download and extract the plugin to:

   archivesspace/plugins/cloudflare/
   

2. Enable the plugin in your ArchivesSpace config/config.rb:

   AppConfig[:plugins] = ['cloudflare']

3. Configure your Cloudflare Turnstile keys in config/config.rb:

   # Cloudflare Turnstile Configuration
   AppConfig[:turnstile_site_key] = "your_site_key_here"
   AppConfig[:turnstile_secret_key] = "your_secret_key_here"

4. Restart ArchivesSpace to load the plugin:

   ./archivesspace.sh stop
   ./archivesspace.sh start

Configuration

Getting Your Cloudflare Turnstile Keys

See CloudFlare documentation https://developers.cloudflare.com/

Configuration Options

Add the following to your config/config.rb:

# Required: Cloudflare Turnstile Site Key (public)
AppConfig[:turnstile_site_key] = "1x00000000000000000000AA"

# Required: Cloudflare Turnstile Secret Key (private)
AppConfig[:turnstile_secret_key] = "1x0000000000000000000000000000000AA"

Note: Replace the example keys above with your actual keys from Cloudflare.

How It Works

1. User Access: When a user visits the public interface, they are intercepted by the Turnstile filter
2. Challenge Display: If not already verified, users see a Turnstile challenge page
3. Verification: Users complete the Turnstile challenge (usually automatic)
4. Session Storage: Upon successful verification, a session flag is set
5. Redirect: Users are redirected to their original destination
6. Subsequent Requests: Verified users can browse without additional challenges (until session expires)

Technical Details

• The plugin uses a before_action filter on ApplicationController to intercept requests
• Turnstile verification is performed server-side via Cloudflare's API
• Session-based verification state prevents repeated challenges
• HTTP timeouts (5s connection, 10s response) prevent hanging requests
• Comprehensive error handling ensures graceful degradation

File Structure

cloudflare/
├── public/
│   ├── controllers/
│   │   └── turnstile_controller.rb    # Handles verification requests
│   ├── lib/
│   │   └── turnstile_filter.rb        # Main filter module
│   ├── routes.rb                       # Plugin routes
│   ├── plugin_init.rb                 # Plugin initialization
│   └── views/
│       └── shared/
│           └── turnstile_challenge.html.erb  # Challenge page template
├── LICENSE
└── README.md

Troubleshooting

Plugin Not Loading

• Verify the plugin is in the correct directory: archivesspace/plugins/cloudflare/
• Check that AppConfig[:plugins] includes 'cloudflare' in config/config.rb
• Review ArchivesSpace logs for initialization errors

Turnstile Challenge Not Appearing

• Verify both AppConfig[:turnstile_site_key] and AppConfig[:turnstile_secret_key] are set
• Check that keys are correct (not test keys in production)
• Review browser console for JavaScript errors
• Check ArchivesSpace logs for configuration errors

Verification Failing

• Verify your secret key is correct
• Check Cloudflare dashboard for site configuration
• Review ArchivesSpace logs for API error messages
• Ensure your server can reach challenges.cloudflare.com

Session Issues

• Clear browser cookies and try again
• Check that session storage is working in ArchivesSpace
• Verify session configuration in ArchivesSpace

View Errors

If you see errors about missing partials (e.g., shared/header), this is expected if your ArchivesSpace installation doesn't have that partial. The plugin handles this gracefully and will continue to work.

Logging

The plugin logs important events to the ArchivesSpace log:

• Configuration errors: When Turnstile keys are missing or invalid
• Verification failures: When Turnstile challenges fail
• API errors: When communication with Cloudflare fails
• HTTP errors: When the API returns non-success status codes

Look for log entries prefixed with [TURNSTILE] for plugin-specific messages.

Security Considerations

• Secret Key: Never commit your secret key to version control
• HTTPS: Always use HTTPS in production to protect the verification process
• Session Security: Ensure ArchivesSpace session security is properly configured
• Rate Limiting: Consider additional rate limiting for the verification endpoint

Acknowledgments

• Cloudflare Turnstile for the bot protection service
• ArchivesSpace for the archival management system

---

Note: This plugin is provided as-is. Make sure to test thoroughly in your environment before deploying to production.