@powforge/captcha

Self-hosted reCAPTCHA alternative using proof-of-work. No tracking, no cookies, no external dependencies.

Your users prove they're human by computing SHA-256 hashes in their browser. No data leaves your site. No third-party scripts. Works offline once loaded.

Quick Start

1. Install

npm install @powforge/captcha

Or use a script tag (no build step needed):

<script src="https://unpkg.com/@powforge/captcha/dist/powforge-captcha.min.js"></script>

2. Add the widget

<form action="/submit" method="POST">
  <input type="text" name="email" placeholder="Email">

  <!-- CAPTCHA mounts here -->
  <div id="pow-captcha"></div>
  <input type="hidden" name="pf_token">

  <button type="submit">Submit</button>
</form>

<script src="powforge-captcha.min.js"
        data-target="#pow-captcha"
        data-server="https://captcha.powforge.dev"
        data-theme="dark"></script>

3. Verify server-side

const { verifyToken } = require('@powforge/captcha/verify');

app.post('/submit', async (req, res) => {
  const result = await verifyToken(req.body.pf_token, {
    server: 'https://captcha.powforge.dev',
  });

  if (!result.valid) {
    return res.status(403).json({ error: 'CAPTCHA failed' });
  }

  // User verified - process form...
});

How It Works

1. Your page loads the widget (5KB gzipped)
2. Widget fetches a challenge from the verification server
3. A Web Worker mines SHA-256 hashes until it finds one with enough leading zero bits
4. The solution is sent to the server for verification
5. Server returns a signed token your backend can validate

Default difficulty: 16 bits (~65,536 hashes, ~4 seconds on average hardware). Adjustable per-challenge.

The proof-of-work is real energy expenditure. Bots pay a real cost. Humans wait a few seconds. No behavioral tracking, no fingerprinting, no cookies.

API

Script Tag (zero config)

<script src="powforge-captcha.min.js"
        data-target="#my-div"
        data-server="https://captcha.powforge.dev"
        data-theme="dark"
        data-difficulty="16"
        data-callback="onVerified">
</script>

ES Module / npm

import { PowCaptcha } from '@powforge/captcha';

const captcha = new PowCaptcha({
  target: '#pow-captcha',
  server: 'https://captcha.powforge.dev',
  theme: 'dark',
  difficulty: 16,
});

captcha.on('verified', ({ token, method }) => {
  console.log('Token:', token);
});

captcha.on('progress', ({ nonce, elapsed, percent }) => {
  console.log(`${percent.toFixed(0)}% complete`);
});

captcha.on('error', (err) => {
  console.error('CAPTCHA error:', err);
});

Methods

Events

DOM Events

The widget also fires a powforge:token CustomEvent on window:

window.addEventListener('powforge:token', (e) => {
  console.log(e.detail.token, e.detail.method);
});

Hidden Input

If your form contains <input type="hidden" name="pf_token">, it is auto-filled when the CAPTCHA is solved.

Server Verification

const { verifyToken } = require('@powforge/captcha/verify');
// or: import { verifyToken } from '@powforge/captcha/verify';

const result = await verifyToken(token, {
  server: 'https://captcha.powforge.dev',  // your self-hosted URL
  timeout: 5000,                            // ms
});

// result: { valid: true, method: 'pow', issued_at: '...', expires_at: '...' }
// or:     { valid: false, reason: 'expired token' }

Comparison

Self-Hosted Server

Run your own verification server:

# Clone the server
git clone https://gitlab.com/powforge/captcha.git
cd captcha

# The server is a single Node.js file, zero npm dependencies for core
node server.js
# Listening on port 3077

Then point the widget at your server:

<script src="powforge-captcha.min.js"
        data-target="#captcha"
        data-server="https://your-server.com:3077">
</script>

Server endpoints:

Difficulty Guide

License

MIT