@powforge/ratelimit

Proof-of-work rate limiting for Express APIs. No API keys, no accounts, no third-party services.

Clients solve a SHA-256 puzzle to prove computational work before accessing your API. Solved proofs grant time-limited tokens for subsequent requests.

Install

npm install @powforge/ratelimit

Quick Start

const express = require('express');
const { powRateLimit } = require('@powforge/ratelimit');

const app = express();

// Protect your API with PoW rate limiting
app.use('/api', powRateLimit({ difficulty: 14 }));

app.get('/api/data', (req, res) => {
  res.json({ message: 'You proved computational work to get here' });
});

app.listen(3000);

How It Works

1. Client requests /api/data without proof
2. Server responds 429 with a SHA-256 challenge
3. Client finds nonce where SHA256(salt + nonce) has N leading zero bits
4. Client retries with X-PoW-Proof: salt:nonce:signature header
5. Server verifies and issues X-PoW-Token for subsequent requests (5 min TTL)

Client Integration

async function fetchWithPoW(url) {
  let res = await fetch(url);
  
  if (res.status === 429) {
    const { challenge } = await res.json();
    const nonce = await solveChallenge(challenge);
    const proof = `${challenge.salt}:${nonce}:${challenge.signature}`;
    res = await fetch(url, {
      headers: { 'X-PoW-Proof': proof }
    });
  }
  
  return res;
}

async function solveChallenge({ salt, difficulty }) {
  for (let nonce = 0; ; nonce++) {
    const hash = await sha256(salt + nonce);
    const bits = parseInt(hash.substring(0, 8), 16);
    if (bits < Math.pow(2, 32 - difficulty)) return nonce;
  }
}

Options

| Option | Default | Description | |--------|---------|-------------| | difficulty | 14 | Leading zero bits (14 = ~16k hashes, <1s) | | tokenTTL | 300 | Token validity in seconds | | challengeTTL | 120 | Challenge validity in seconds | | secret | auto | HMAC signing secret | | skipIf | null | (req) => boolean to bypass PoW |

Difficulty Guide

| Difficulty | Expected Hashes | Browser Time | Use Case | |-----------|----------------|-------------|----------| | 10 | 1,024 | ~25ms | Light protection | | 14 | 16,384 | ~350ms | Standard API protection | | 18 | 262,144 | ~12s | High-value endpoints | | 20 | 1,048,576 | ~23s | Rate-limit heavy consumers |

Data from empirical experiments on AMD EPYC 7443P. Browser times ~5x slower than server.

Why PoW Instead of API Keys?

• No accounts needed: Clients prove work, not identity
• No rate limit state: Server is stateless (tokens are self-contained HMACs)
• Bot deterrence: Automated scrapers must spend real CPU time per request
• Privacy-first: No tracking, no IP logging, no third-party calls
• Softwar thesis: Access costs energy, not credentials

Part of the PowForge Project

Built as part of the Softwar thesis research, testing proof-of-work as a universal access control mechanism.

• PoW CAPTCHA - Browser widget
• @powforge/ratelimit - API middleware

License

MIT