Implement hashcash proof-of-work for session creation #11

New Issue

2026-02-11T03:06:41+01:00

clawbot commented

2026-02-11 03:06:41 +01:00

Problem

Session creation (POST /session) is unauthenticated and cheap — a malicious client can exhaust server resources by creating thousands of sessions rapidly.

Solution

Require a hashcash proof-of-work token on session creation requests. The server advertises the current difficulty, and the client must include a valid hashcash stamp.

How it works

Client requests current difficulty: GET /server returns a hashcash_bits field (e.g. 20)
Client computes a hashcash stamp with the required number of leading zero bits
Client includes the stamp in POST /session request (e.g. "proof": "1:20:260210:session::..." )
Server verifies the stamp before creating the session

Adaptive difficulty

Low load (few active sessions): low difficulty (e.g. 16 bits) — instant on modern hardware
Medium load: moderate difficulty (e.g. 20-22 bits) — ~1 second
High load: high difficulty (e.g. 24-28 bits) — seconds to minutes
Under attack: very high difficulty — legitimate users wait a few seconds, attackers pay exponentially more CPU

The difficulty scales with active session count or session creation rate over a sliding window.

Why hashcash

Fits the IRC philosophy: no accounts, no CAPTCHAs, no external dependencies
Clients can compute it offline — no server round-trip for a challenge
Proven mechanism (used in early spam prevention, Bitcoin mining is a descendant)
Simple to implement in any language

Not MVP-blocking

This is a hardening feature for production deployments. The MVP can ship without it.

## Problem Session creation (`POST /session`) is unauthenticated and cheap — a malicious client can exhaust server resources by creating thousands of sessions rapidly. ## Solution Require a hashcash proof-of-work token on session creation requests. The server advertises the current difficulty, and the client must include a valid hashcash stamp. ### How it works 1. Client requests current difficulty: `GET /server` returns a `hashcash_bits` field (e.g. 20) 2. Client computes a hashcash stamp with the required number of leading zero bits 3. Client includes the stamp in `POST /session` request (e.g. `"proof": "1:20:260210:session::..."` ) 4. Server verifies the stamp before creating the session ### Adaptive difficulty - **Low load** (few active sessions): low difficulty (e.g. 16 bits) — instant on modern hardware - **Medium load**: moderate difficulty (e.g. 20-22 bits) — ~1 second - **High load**: high difficulty (e.g. 24-28 bits) — seconds to minutes - **Under attack**: very high difficulty — legitimate users wait a few seconds, attackers pay exponentially more CPU The difficulty scales with active session count or session creation rate over a sliding window. ### Why hashcash - Fits the IRC philosophy: no accounts, no CAPTCHAs, no external dependencies - Clients can compute it offline — no server round-trip for a challenge - Proven mechanism (used in early spam prevention, Bitcoin mining is a descendant) - Simple to implement in any language ### Not MVP-blocking This is a hardening feature for production deployments. The MVP can ship without it.