README

Altcha proof-of-work spam protection for CakePHP 5. Privacy-friendly, no external services, no tracking.

Uses Altcha to generate SHA-256 challenges that are solved client-side. No CAPTCHA images, no Google dependencies.

Install

composer require azzmin/cakephp-altcha

Setup

1. Load the plugin in src/Application.php:

$this->addPlugin('Altcha');

2. In your controller load the component and helper:

public function initialize(): void
{
    parent::initialize();
    $this->loadComponent('Altcha.Altcha');
    $this->viewBuilder()->addHelper('Altcha.Altcha');
}

3. Verify on POST in your action, before processing the form:

if ($this->request->is('post')) {
    if (!$this->Altcha->verify($this->request)) {
        $this->Flash->error('Please complete the verification.');
        return null;
    }

    // process form...
}

4. Render the widget in your template, before the submit button:

<?= $this->Altcha->widget() ?>

That's it. No database, no routes, no configuration required.

Options

Pass an array to widget() to customise:

<?= $this->Altcha->widget(['hidelogo' => true]) ?>

If you change name, pass the same value to verify:

$this->Altcha->verify($this->request, 'my_field_name');

Configuration

All optional. Defaults work out of the box using Security.salt from app_local.php.

Add to config/app_local.php to override:

'Altcha' => [
    'hmacKey' => 'your-custom-key',    // defaults to Security.salt
    'maxNumber' => 100000,              // higher = harder for bots
    'saltLength' => 12,
    'jsUrl' => 'https://cdn.jsdelivr.net/npm/altcha@latest/dist/altcha.js',
],

How it works

1. Server generates a SHA-256 challenge with a HMAC signature
2. Client solves the proof-of-work in the browser (finds the nonce)
3. Solution is submitted as a hidden form field
4. Server verifies the hash and HMAC signature

No data sent to third parties. All computation happens in the browser.

Requirements

• PHP 8.1+
• CakePHP 5.0+

CakePHP 5.3 Compatibility

Note: This plugin uses AltchaPlugin as the primary plugin class following CakePHP 5.3 conventions. A Plugin class is maintained for backward compatibility with CakePHP 5.0-5.2.

Migration for CakePHP 5.3+ Users

If you're using CakePHP 5.3 or later, the plugin will automatically use the new AltchaPlugin class. No changes are needed to your code.

Deprecation Notice

If you see a deprecation warning about the Plugin class when using CakePHP 5.3+, this is expected for backward compatibility. The Plugin class will be removed in the next major version of this plugin.

Future Changes

In a future major release (2.0.0), the Plugin class will be removed and only AltchaPlugin will remain. If you're only using CakePHP 5.3+, you don't need to take any action.

License

Apache-2.0