feat: per-channel hashcash proof-of-work for PRIVMSG anti-spam (#79)

closes #12

## Summary

Implements per-channel hashcash proof-of-work requirement for PRIVMSG as an anti-spam mechanism. Channel operators set a difficulty level via `MODE +H <bits>`, and clients must compute a proof-of-work stamp bound to the channel name and message body before sending.

## Changes

### Database
- Added `hashcash_bits` column to `channels` table (default 0 = no requirement)
- Added `spent_hashcash` table with `stamp_hash` unique key and `created_at` for TTL pruning
- New queries: `GetChannelHashcashBits`, `SetChannelHashcashBits`, `RecordSpentHashcash`, `IsHashcashSpent`, `PruneSpentHashcash`

### Hashcash Validation (`internal/hashcash/channel.go`)
- `ChannelValidator` type for per-channel stamp validation
- `BodyHash()` computes hex-encoded SHA-256 of message body
- `StampHash()` computes deterministic hash of stamp for spent-token key
- `MintChannelStamp()` generates valid stamps (for clients)
- Stamp format: `1:bits:YYMMDD:channel:bodyhash:counter`
- Validates: version, difficulty, date freshness (48h), channel binding, body hash binding, proof-of-work

### Handler Changes (`internal/handlers/api.go`)
- `validateChannelHashcash()` + `verifyChannelStamp()` — checks hashcash on PRIVMSG to protected channels
- `extractHashcashFromMeta()` — parses hashcash stamp from meta JSON
- `applyChannelMode()` / `setHashcashMode()` / `clearHashcashMode()` — MODE +H/-H support
- `queryChannelMode()` — shows +nH in mode query when hashcash is set
- Meta field now passed through the full dispatch chain (dispatchCommand → handlePrivmsg → handleChannelMsg → sendChannelMsg → fanOut → InsertMessage)
- ISUPPORT updated: `CHANMODES=,H,,imnst` (H in type B = parameter when set)

### Replay Prevention
- Spent stamps persisted to SQLite `spent_hashcash` table
- 1-year TTL (per issue requirements)
- Automatic pruning in cleanup loop

### Client Support (`internal/cli/api/hashcash.go`)
- `MintChannelHashcash(bits, channel, body)` — computes stamps for channel messages

### Tests
- **12 unit tests** in `internal/hashcash/channel_test.go`: happy path, wrong channel, wrong body hash, insufficient bits, zero bits skip, bad format, bad version, expired stamp, missing body hash, body hash determinism, stamp hash, mint+validate round-trip
- **10 integration tests** in `internal/handlers/api_test.go`: set mode, query mode, clear mode, reject no stamp, accept valid stamp, reject replayed stamp, no requirement works, invalid bits range, missing bits arg

### README
- Added `+H` to channel modes table
- Added "Per-Channel Hashcash (Anti-Spam)" section with full documentation
- Updated `meta` field description to mention hashcash

## How It Works

1. Channel operator sets requirement: `MODE #general +H 20` (20 bits)
2. Client mints stamp: computes SHA-256 hashcash bound to `#general` + SHA-256(body)
3. Client sends PRIVMSG with `meta.hashcash` field containing the stamp
4. Server validates stamp, checks spent cache, records as spent, relays message
5. Replayed stamps are rejected for 1 year

## Docker Build

`docker build .` passes clean (formatting, linting, all tests).

Co-authored-by: user <user@Mac.lan guest wan>
Co-authored-by: Jeffrey Paul <sneak@noreply.example.org>
Reviewed-on: #79
Co-authored-by: clawbot <clawbot@noreply.example.org>
Co-committed-by: clawbot <clawbot@noreply.example.org>

internal/handlers/api.go

@@ -3,6 +3,7 @@ package handlers
 import (
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"net/http"
 	"regexp"
@@ -11,10 +12,16 @@ import (
 	"time"
 
 	"git.eeqj.de/sneak/neoirc/internal/db"
+	"git.eeqj.de/sneak/neoirc/internal/hashcash"
 	"git.eeqj.de/sneak/neoirc/pkg/irc"
 	"github.com/go-chi/chi/v5"
 )
 
+var (
+	errHashcashRequired = errors.New("hashcash required")
+	errHashcashReused   = errors.New("hashcash reused")
+)
+
 var validNickRe = regexp.MustCompile(
 	`^[a-zA-Z_][a-zA-Z0-9_\-\[\]\\^{}|` + "`" + `]{0,31}$`,
 )
@@ -88,10 +95,11 @@ func (hdlr *Handlers) fanOut(
 	request *http.Request,
 	command, from, target string,
 	body json.RawMessage,
+	meta json.RawMessage,
 	sessionIDs []int64,
 ) (string, error) {
 	dbID, msgUUID, err := hdlr.params.Database.InsertMessage(
-		request.Context(), command, from, target, nil, body, nil,
+		request.Context(), command, from, target, nil, body, meta,
 	)
 	if err != nil {
 		return "", fmt.Errorf("insert message: %w", err)
@@ -117,10 +125,11 @@ func (hdlr *Handlers) fanOutSilent(
 	request *http.Request,
 	command, from, target string,
 	body json.RawMessage,
+	meta json.RawMessage,
 	sessionIDs []int64,
 ) error {
 	_, err := hdlr.fanOut(
-		request, command, from, target, body, sessionIDs,
+		request, command, from, target, body, meta, sessionIDs,
 	)
 
 	return err
@@ -294,7 +303,7 @@ func (hdlr *Handlers) deliverWelcome(
 		[]string{
 			"CHANTYPES=#",
 			"NICKLEN=32",
-			"CHANMODES=,,," + "imnst",
+			"CHANMODES=,,H," + "imnst",
 			"NETWORK=neoirc",
 			"CASEMAPPING=ascii",
 		},
@@ -825,7 +834,7 @@ func (hdlr *Handlers) HandleSendCommand() http.HandlerFunc {
 			writer, request,
 			sessionID, clientID, nick,
 			payload.Command, payload.To,
-			payload.Body, bodyLines,
+			payload.Body, payload.Meta, bodyLines,
 		)
 	}
 }
@@ -836,6 +845,7 @@ func (hdlr *Handlers) dispatchCommand(
 	sessionID, clientID int64,
 	nick, command, target string,
 	body json.RawMessage,
+	meta json.RawMessage,
 	bodyLines func() []string,
 ) {
 	switch command {
@@ -848,7 +858,7 @@ func (hdlr *Handlers) dispatchCommand(
 		hdlr.handlePrivmsg(
 			writer, request,
 			sessionID, clientID, nick,
-			command, target, body, bodyLines,
+			command, target, body, meta, bodyLines,
 		)
 	case irc.CmdJoin:
 		hdlr.handleJoin(
@@ -949,6 +959,7 @@ func (hdlr *Handlers) handlePrivmsg(
 	sessionID, clientID int64,
 	nick, command, target string,
 	body json.RawMessage,
+	meta json.RawMessage,
 	bodyLines func() []string,
 ) {
 	if target == "" {
@@ -986,7 +997,7 @@ func (hdlr *Handlers) handlePrivmsg(
 		hdlr.handleChannelMsg(
 			writer, request,
 			sessionID, clientID, nick,
-			command, target, body,
+			command, target, body, meta,
 		)
 
 		return
@@ -995,7 +1006,7 @@ func (hdlr *Handlers) handlePrivmsg(
 	hdlr.handleDirectMsg(
 		writer, request,
 		sessionID, clientID, nick,
-		command, target, body,
+		command, target, body, meta,
 	)
 }
 
@@ -1026,6 +1037,7 @@ func (hdlr *Handlers) handleChannelMsg(
 	sessionID, clientID int64,
 	nick, command, target string,
 	body json.RawMessage,
+	meta json.RawMessage,
 ) {
 	chID, err := hdlr.params.Database.GetChannelByName(
 		request.Context(), target,
@@ -1066,9 +1078,172 @@ func (hdlr *Handlers) handleChannelMsg(
 		return
 	}
 
-	hdlr.sendChannelMsg(
-		writer, request, command, nick, target, body, chID,
+	hashcashErr := hdlr.validateChannelHashcash(
+		request, clientID, sessionID,
+		writer, nick, target, body, meta, chID,
 	)
+	if hashcashErr != nil {
+		return
+	}
+
+	hdlr.sendChannelMsg(
+		writer, request, command, nick, target,
+		body, meta, chID,
+	)
+}
+
+// validateChannelHashcash checks whether the channel
+// requires hashcash proof-of-work for messages and
+// validates the stamp from the message meta field.
+// Returns nil on success or if the channel has no
+// hashcash requirement. On failure, it sends the
+// appropriate IRC error and returns a non-nil error.
+func (hdlr *Handlers) validateChannelHashcash(
+	request *http.Request,
+	clientID, sessionID int64,
+	writer http.ResponseWriter,
+	nick, target string,
+	body json.RawMessage,
+	meta json.RawMessage,
+	chID int64,
+) error {
+	ctx := request.Context()
+
+	bits, bitsErr := hdlr.params.Database.GetChannelHashcashBits(
+		ctx, chID,
+	)
+	if bitsErr != nil {
+		hdlr.log.Error(
+			"get channel hashcash bits", "error", bitsErr,
+		)
+		hdlr.respondError(
+			writer, request,
+			"internal error",
+			http.StatusInternalServerError,
+		)
+
+		return fmt.Errorf("channel hashcash bits: %w", bitsErr)
+	}
+
+	if bits <= 0 {
+		return nil
+	}
+
+	stamp := hdlr.extractHashcashFromMeta(meta)
+	if stamp == "" {
+		hdlr.respondIRCError(
+			writer, request, clientID, sessionID,
+			irc.ErrCannotSendToChan, nick, []string{target},
+			"Channel requires hashcash proof-of-work",
+		)
+
+		return errHashcashRequired
+	}
+
+	return hdlr.verifyChannelStamp(
+		request, writer,
+		clientID, sessionID,
+		nick, target, body, stamp, bits,
+	)
+}
+
+// verifyChannelStamp validates a channel hashcash stamp
+// and checks for replay attacks.
+func (hdlr *Handlers) verifyChannelStamp(
+	request *http.Request,
+	writer http.ResponseWriter,
+	clientID, sessionID int64,
+	nick, target string,
+	body json.RawMessage,
+	stamp string,
+	bits int,
+) error {
+	ctx := request.Context()
+	bodyHashStr := hashcash.BodyHash(body)
+
+	valErr := hdlr.channelHashcash.ValidateStamp(
+		stamp, bits, target, bodyHashStr,
+	)
+	if valErr != nil {
+		hdlr.respondIRCError(
+			writer, request, clientID, sessionID,
+			irc.ErrCannotSendToChan, nick, []string{target},
+			"Invalid hashcash: "+valErr.Error(),
+		)
+
+		return fmt.Errorf("channel hashcash: %w", valErr)
+	}
+
+	stampKey := hashcash.StampHash(stamp)
+
+	spent, spentErr := hdlr.params.Database.IsHashcashSpent(
+		ctx, stampKey,
+	)
+	if spentErr != nil {
+		hdlr.log.Error(
+			"check spent hashcash", "error", spentErr,
+		)
+		hdlr.respondError(
+			writer, request,
+			"internal error",
+			http.StatusInternalServerError,
+		)
+
+		return fmt.Errorf("check spent hashcash: %w", spentErr)
+	}
+
+	if spent {
+		hdlr.respondIRCError(
+			writer, request, clientID, sessionID,
+			irc.ErrCannotSendToChan, nick, []string{target},
+			"Hashcash stamp already used",
+		)
+
+		return errHashcashReused
+	}
+
+	recordErr := hdlr.params.Database.RecordSpentHashcash(
+		ctx, stampKey,
+	)
+	if recordErr != nil {
+		hdlr.log.Error(
+			"record spent hashcash", "error", recordErr,
+		)
+	}
+
+	return nil
+}
+
+// extractHashcashFromMeta parses the meta JSON and
+// returns the hashcash stamp string, or empty string
+// if not present.
+func (hdlr *Handlers) extractHashcashFromMeta(
+	meta json.RawMessage,
+) string {
+	if len(meta) == 0 {
+		return ""
+	}
+
+	var metaMap map[string]json.RawMessage
+
+	err := json.Unmarshal(meta, &metaMap)
+	if err != nil {
+		return ""
+	}
+
+	raw, ok := metaMap["hashcash"]
+	if !ok {
+		return ""
+	}
+
+	var stamp string
+
+	err = json.Unmarshal(raw, &stamp)
+	if err != nil {
+		return ""
+	}
+
+	return stamp
 }
 
 func (hdlr *Handlers) sendChannelMsg(
@@ -1076,6 +1251,7 @@ func (hdlr *Handlers) sendChannelMsg(
 	request *http.Request,
 	command, nick, target string,
 	body json.RawMessage,
+	meta json.RawMessage,
 	chID int64,
 ) {
 	memberIDs, err := hdlr.params.Database.GetChannelMemberIDs(
@@ -1095,7 +1271,7 @@ func (hdlr *Handlers) sendChannelMsg(
 	}
 
 	msgUUID, err := hdlr.fanOut(
-		request, command, nick, target, body, memberIDs,
+		request, command, nick, target, body, meta, memberIDs,
 	)
 	if err != nil {
 		hdlr.log.Error("send message failed", "error", err)
@@ -1119,6 +1295,7 @@ func (hdlr *Handlers) handleDirectMsg(
 	sessionID, clientID int64,
 	nick, command, target string,
 	body json.RawMessage,
+	meta json.RawMessage,
 ) {
 	targetSID, err := hdlr.params.Database.GetSessionByNick(
 		request.Context(), target,
@@ -1143,7 +1320,7 @@ func (hdlr *Handlers) handleDirectMsg(
 	}
 
 	msgUUID, err := hdlr.fanOut(
-		request, command, nick, target, body, recipients,
+		request, command, nick, target, body, meta, recipients,
 	)
 	if err != nil {
 		hdlr.log.Error("send dm failed", "error", err)
@@ -1254,7 +1431,7 @@ func (hdlr *Handlers) executeJoin(
 	)
 
 	_ = hdlr.fanOutSilent(
-		request, irc.CmdJoin, nick, channel, nil, memberIDs,
+		request, irc.CmdJoin, nick, channel, nil, nil, memberIDs,
 	)
 
 	hdlr.deliverJoinNumerics(
@@ -1424,7 +1601,7 @@ func (hdlr *Handlers) handlePart(
 	)
 
 	_ = hdlr.fanOutSilent(
-		request, irc.CmdPart, nick, channel, body, memberIDs,
+		request, irc.CmdPart, nick, channel, body, nil, memberIDs,
 	)
 
 	err = hdlr.params.Database.PartChannel(
@@ -1704,7 +1881,7 @@ func (hdlr *Handlers) executeTopic(
 	)
 
 	_ = hdlr.fanOutSilent(
-		request, irc.CmdTopic, nick, channel, body, memberIDs,
+		request, irc.CmdTopic, nick, channel, body, nil, memberIDs,
 	)
 
 	hdlr.enqueueNumeric(
@@ -1867,11 +2044,10 @@ func (hdlr *Handlers) handleMode(
 		return
 	}
 
-	_ = bodyLines
-
 	hdlr.handleChannelMode(
 		writer, request,
 		sessionID, clientID, nick, channel,
+		bodyLines,
 	)
 }
 
@@ -1880,6 +2056,7 @@ func (hdlr *Handlers) handleChannelMode(
 	request *http.Request,
 	sessionID, clientID int64,
 	nick, channel string,
+	bodyLines func() []string,
 ) {
 	ctx := request.Context()
 
@@ -1896,10 +2073,47 @@ func (hdlr *Handlers) handleChannelMode(
 		return
 	}
 
+	lines := bodyLines()
+	if len(lines) > 0 {
+		hdlr.applyChannelMode(
+			writer, request,
+			sessionID, clientID, nick,
+			channel, chID, lines,
+		)
+
+		return
+	}
+
+	hdlr.queryChannelMode(
+		writer, request,
+		sessionID, clientID, nick, channel, chID,
+	)
+}
+
+// queryChannelMode sends RPL_CHANNELMODEIS and
+// RPL_CREATIONTIME for a channel. Includes +H if
+// the channel has a hashcash requirement.
+func (hdlr *Handlers) queryChannelMode(
+	writer http.ResponseWriter,
+	request *http.Request,
+	sessionID, clientID int64,
+	nick, channel string,
+	chID int64,
+) {
+	ctx := request.Context()
+
+	modeStr := "+n"
+
+	bits, bitsErr := hdlr.params.Database.
+		GetChannelHashcashBits(ctx, chID)
+	if bitsErr == nil && bits > 0 {
+		modeStr = fmt.Sprintf("+nH %d", bits)
+	}
+
 	// 324 RPL_CHANNELMODEIS
 	hdlr.enqueueNumeric(
 		ctx, clientID, irc.RplChannelModeIs, nick,
-		[]string{channel, "+n"}, "",
+		[]string{channel, modeStr}, "",
 	)
 
 	// 329 RPL_CREATIONTIME
@@ -1924,6 +2138,156 @@ func (hdlr *Handlers) handleChannelMode(
 		http.StatusOK)
 }
 
+// applyChannelMode handles setting channel modes.
+// Currently supports +H/-H for hashcash bits.
+func (hdlr *Handlers) applyChannelMode(
+	writer http.ResponseWriter,
+	request *http.Request,
+	sessionID, clientID int64,
+	nick, channel string,
+	chID int64,
+	modeArgs []string,
+) {
+	ctx := request.Context()
+	modeStr := modeArgs[0]
+
+	switch modeStr {
+	case "+H":
+		hdlr.setHashcashMode(
+			writer, request,
+			sessionID, clientID, nick,
+			channel, chID, modeArgs,
+		)
+	case "-H":
+		hdlr.clearHashcashMode(
+			writer, request,
+			sessionID, clientID, nick,
+			channel, chID,
+		)
+	default:
+		// Unknown or unsupported mode change.
+		hdlr.enqueueNumeric(
+			ctx, clientID, irc.ErrUnknownMode, nick,
+			[]string{modeStr},
+			"is unknown mode char to me",
+		)
+		hdlr.broker.Notify(sessionID)
+		hdlr.respondJSON(writer, request,
+			map[string]string{"status": "error"},
+			http.StatusOK)
+	}
+}
+
+const (
+	// minHashcashBits is the minimum allowed hashcash
+	// difficulty for channels.
+	minHashcashBits = 1
+	// maxHashcashBits is the maximum allowed hashcash
+	// difficulty for channels.
+	maxHashcashBits = 40
+)
+
+// setHashcashMode handles MODE #channel +H <bits>.
+func (hdlr *Handlers) setHashcashMode(
+	writer http.ResponseWriter,
+	request *http.Request,
+	sessionID, clientID int64,
+	nick, channel string,
+	chID int64,
+	modeArgs []string,
+) {
+	ctx := request.Context()
+
+	if len(modeArgs) < 2 { //nolint:mnd // +H requires a bits arg
+		hdlr.respondIRCError(
+			writer, request, clientID, sessionID,
+			irc.ErrNeedMoreParams, nick, []string{irc.CmdMode},
+			"Not enough parameters (+H requires bits)",
+		)
+
+		return
+	}
+
+	bits, err := strconv.Atoi(modeArgs[1])
+	if err != nil || bits < minHashcashBits ||
+		bits > maxHashcashBits {
+		hdlr.respondIRCError(
+			writer, request, clientID, sessionID,
+			irc.ErrUnknownMode, nick, []string{"+H"},
+			fmt.Sprintf(
+				"Invalid hashcash bits (must be %d-%d)",
+				minHashcashBits, maxHashcashBits,
+			),
+		)
+
+		return
+	}
+
+	err = hdlr.params.Database.SetChannelHashcashBits(
+		ctx, chID, bits,
+	)
+	if err != nil {
+		hdlr.log.Error(
+			"set channel hashcash bits", "error", err,
+		)
+		hdlr.respondError(
+			writer, request,
+			"internal error",
+			http.StatusInternalServerError,
+		)
+
+		return
+	}
+
+	hdlr.enqueueNumeric(
+		ctx, clientID, irc.RplChannelModeIs, nick,
+		[]string{
+			channel,
+			fmt.Sprintf("+H %d", bits),
+		}, "",
+	)
+	hdlr.broker.Notify(sessionID)
+	hdlr.respondJSON(writer, request,
+		map[string]string{"status": "ok"},
+		http.StatusOK)
+}
+
+// clearHashcashMode handles MODE #channel -H.
+func (hdlr *Handlers) clearHashcashMode(
+	writer http.ResponseWriter,
+	request *http.Request,
+	sessionID, clientID int64,
+	nick, channel string,
+	chID int64,
+) {
+	ctx := request.Context()
+
+	err := hdlr.params.Database.SetChannelHashcashBits(
+		ctx, chID, 0,
+	)
+	if err != nil {
+		hdlr.log.Error(
+			"clear channel hashcash bits", "error", err,
+		)
+		hdlr.respondError(
+			writer, request,
+			"internal error",
+			http.StatusInternalServerError,
+		)
+
+		return
+	}
+
+	hdlr.enqueueNumeric(
+		ctx, clientID, irc.RplChannelModeIs, nick,
+		[]string{channel, "+n"}, "",
+	)
+	hdlr.broker.Notify(sessionID)
+	hdlr.respondJSON(writer, request,
+		map[string]string{"status": "ok"},
+		http.StatusOK)
+}
+
 // handleNames sends NAMES reply for a channel.
 func (hdlr *Handlers) handleNames(
 	writer http.ResponseWriter,

internal/handlers/api_test.go

@@ -22,6 +22,7 @@ import (
 	"git.eeqj.de/sneak/neoirc/internal/db"
 	"git.eeqj.de/sneak/neoirc/internal/globals"
 	"git.eeqj.de/sneak/neoirc/internal/handlers"
+	"git.eeqj.de/sneak/neoirc/internal/hashcash"
 	"git.eeqj.de/sneak/neoirc/internal/healthcheck"
 	"git.eeqj.de/sneak/neoirc/internal/logger"
 	"git.eeqj.de/sneak/neoirc/internal/middleware"
@@ -2157,3 +2158,397 @@ func TestNickBroadcastToChannels(t *testing.T) {
 		)
 	}
 }
+
+// --- Channel Hashcash Tests ---
+
+const (
+	metaKey     = "meta"
+	modeCmd     = "MODE"
+	hashcashKey = "hashcash"
+)
+
+func mintTestChannelHashcash(
+	tb testing.TB,
+	bits int,
+	channel string,
+	body json.RawMessage,
+) string {
+	tb.Helper()
+
+	bodyHash := hashcash.BodyHash(body)
+
+	return hashcash.MintChannelStamp(bits, channel, bodyHash)
+}
+
+func TestChannelHashcashSetMode(t *testing.T) {
+	tserver := newTestServer(t)
+	token := tserver.createSession("hcmode_user")
+
+	tserver.sendCommand(token, map[string]any{
+		commandKey: joinCmd, toKey: "#hctest",
+	})
+
+	_, lastID := tserver.pollMessages(token, 0)
+
+	// Set hashcash bits to 2 via MODE +H.
+	status, _ := tserver.sendCommand(
+		token,
+		map[string]any{
+			commandKey: modeCmd,
+			toKey:      "#hctest",
+			bodyKey:    []string{"+H", "2"},
+		},
+	)
+	if status != http.StatusOK {
+		t.Fatalf("expected 200, got %d", status)
+	}
+
+	msgs, _ := tserver.pollMessages(token, lastID)
+
+	// Should get RPL_CHANNELMODEIS (324) confirming +H.
+	if !findNumeric(msgs, "324") {
+		t.Fatalf(
+			"expected RPL_CHANNELMODEIS (324), got %v",
+			msgs,
+		)
+	}
+}
+
+func TestChannelHashcashQueryMode(t *testing.T) {
+	tserver := newTestServer(t)
+	token := tserver.createSession("hcquery_user")
+
+	tserver.sendCommand(token, map[string]any{
+		commandKey: joinCmd, toKey: "#hcquery",
+	})
+
+	// Set hashcash bits.
+	tserver.sendCommand(token, map[string]any{
+		commandKey: modeCmd,
+		toKey:      "#hcquery",
+		bodyKey:    []string{"+H", "5"},
+	})
+
+	_, lastID := tserver.pollMessages(token, 0)
+
+	// Query mode — should show +nH.
+	tserver.sendCommand(token, map[string]any{
+		commandKey: modeCmd,
+		toKey:      "#hcquery",
+	})
+
+	msgs, _ := tserver.pollMessages(token, lastID)
+
+	found := false
+
+	for _, msg := range msgs {
+		code, ok := msg["code"].(float64)
+		if ok && int(code) == 324 {
+			found = true
+		}
+	}
+
+	if !found {
+		t.Fatalf(
+			"expected RPL_CHANNELMODEIS (324), got %v",
+			msgs,
+		)
+	}
+}
+
+func TestChannelHashcashClearMode(t *testing.T) {
+	tserver := newTestServer(t)
+	token := tserver.createSession("hcclear_user")
+
+	tserver.sendCommand(token, map[string]any{
+		commandKey: joinCmd, toKey: "#hcclear",
+	})
+
+	// Set hashcash bits.
+	tserver.sendCommand(token, map[string]any{
+		commandKey: modeCmd,
+		toKey:      "#hcclear",
+		bodyKey:    []string{"+H", "5"},
+	})
+
+	// Clear hashcash bits.
+	status, _ := tserver.sendCommand(token, map[string]any{
+		commandKey: modeCmd,
+		toKey:      "#hcclear",
+		bodyKey:    []string{"-H"},
+	})
+	if status != http.StatusOK {
+		t.Fatalf("expected 200, got %d", status)
+	}
+
+	// Now message should succeed without hashcash.
+	status, result := tserver.sendCommand(
+		token,
+		map[string]any{
+			commandKey: privmsgCmd,
+			toKey:      "#hcclear",
+			bodyKey:    []string{"test message"},
+		},
+	)
+	if status != http.StatusOK {
+		t.Fatalf(
+			"expected 200, got %d: %v", status, result,
+		)
+	}
+}
+
+func TestChannelHashcashRejectNoStamp(t *testing.T) {
+	tserver := newTestServer(t)
+	token := tserver.createSession("hcreject_user")
+
+	tserver.sendCommand(token, map[string]any{
+		commandKey: joinCmd, toKey: "#hcreject",
+	})
+
+	// Set hashcash requirement.
+	tserver.sendCommand(token, map[string]any{
+		commandKey: modeCmd,
+		toKey:      "#hcreject",
+		bodyKey:    []string{"+H", "2"},
+	})
+
+	_, lastID := tserver.pollMessages(token, 0)
+
+	// Send message without hashcash — should fail.
+	status, _ := tserver.sendCommand(
+		token,
+		map[string]any{
+			commandKey: privmsgCmd,
+			toKey:      "#hcreject",
+			bodyKey:    []string{"spam message"},
+		},
+	)
+	if status != http.StatusOK {
+		t.Fatalf("expected 200, got %d", status)
+	}
+
+	msgs, _ := tserver.pollMessages(token, lastID)
+
+	// Should get ERR_CANNOTSENDTOCHAN (404).
+	if !findNumeric(msgs, "404") {
+		t.Fatalf(
+			"expected ERR_CANNOTSENDTOCHAN (404), got %v",
+			msgs,
+		)
+	}
+}
+
+func TestChannelHashcashAcceptValidStamp(t *testing.T) {
+	tserver := newTestServer(t)
+	token := tserver.createSession("hcaccept_user")
+
+	tserver.sendCommand(token, map[string]any{
+		commandKey: joinCmd, toKey: "#hcaccept",
+	})
+
+	// Set hashcash requirement (2 bits = fast to mint).
+	tserver.sendCommand(token, map[string]any{
+		commandKey: modeCmd,
+		toKey:      "#hcaccept",
+		bodyKey:    []string{"+H", "2"},
+	})
+
+	_, lastID := tserver.pollMessages(token, 0)
+
+	// Mint a valid hashcash stamp.
+	msgBody, marshalErr := json.Marshal(
+		[]string{"hello world"},
+	)
+	if marshalErr != nil {
+		t.Fatal(marshalErr)
+	}
+
+	stamp := mintTestChannelHashcash(
+		t, 2, "#hcaccept", msgBody,
+	)
+
+	// Send message with valid hashcash.
+	status, result := tserver.sendCommand(
+		token,
+		map[string]any{
+			commandKey: privmsgCmd,
+			toKey:      "#hcaccept",
+			bodyKey:    []string{"hello world"},
+			metaKey: map[string]any{
+				hashcashKey: stamp,
+			},
+		},
+	)
+	if status != http.StatusOK {
+		t.Fatalf(
+			"expected 200, got %d: %v", status, result,
+		)
+	}
+
+	if result["id"] == nil || result["id"] == "" {
+		t.Fatal("expected message id for valid hashcash")
+	}
+
+	// Verify the message was delivered.
+	msgs, _ := tserver.pollMessages(token, lastID)
+	if !findMessage(msgs, privmsgCmd, "hcaccept_user") {
+		t.Fatalf(
+			"message not received: %v", msgs,
+		)
+	}
+}
+
+func TestChannelHashcashRejectReplayedStamp(t *testing.T) {
+	tserver := newTestServer(t)
+	token := tserver.createSession("hcreplay_user")
+
+	tserver.sendCommand(token, map[string]any{
+		commandKey: joinCmd, toKey: "#hcreplay",
+	})
+
+	// Set hashcash requirement.
+	tserver.sendCommand(token, map[string]any{
+		commandKey: modeCmd,
+		toKey:      "#hcreplay",
+		bodyKey:    []string{"+H", "2"},
+	})
+
+	_, _ = tserver.pollMessages(token, 0)
+
+	// Mint and send once — should succeed.
+	msgBody, marshalErr := json.Marshal(
+		[]string{"unique msg"},
+	)
+	if marshalErr != nil {
+		t.Fatal(marshalErr)
+	}
+
+	stamp := mintTestChannelHashcash(
+		t, 2, "#hcreplay", msgBody,
+	)
+
+	status, _ := tserver.sendCommand(
+		token,
+		map[string]any{
+			commandKey: privmsgCmd,
+			toKey:      "#hcreplay",
+			bodyKey:    []string{"unique msg"},
+			metaKey: map[string]any{
+				hashcashKey: stamp,
+			},
+		},
+	)
+	if status != http.StatusOK {
+		t.Fatalf("expected 200, got %d", status)
+	}
+
+	_, lastID := tserver.pollMessages(token, 0)
+
+	// Replay the same stamp — should fail.
+	status, _ = tserver.sendCommand(
+		token,
+		map[string]any{
+			commandKey: privmsgCmd,
+			toKey:      "#hcreplay",
+			bodyKey:    []string{"unique msg"},
+			metaKey: map[string]any{
+				hashcashKey: stamp,
+			},
+		},
+	)
+	if status != http.StatusOK {
+		t.Fatalf("expected 200, got %d", status)
+	}
+
+	msgs, _ := tserver.pollMessages(token, lastID)
+
+	// Should get ERR_CANNOTSENDTOCHAN (404).
+	if !findNumeric(msgs, "404") {
+		t.Fatalf(
+			"expected replay rejection (404), got %v",
+			msgs,
+		)
+	}
+}
+
+func TestChannelHashcashNoRequirementWorks(t *testing.T) {
+	tserver := newTestServer(t)
+	token := tserver.createSession("hcnone_user")
+
+	tserver.sendCommand(token, map[string]any{
+		commandKey: joinCmd, toKey: "#nohashcash",
+	})
+
+	// No hashcash set — message should work.
+	status, result := tserver.sendCommand(
+		token,
+		map[string]any{
+			commandKey: privmsgCmd,
+			toKey:      "#nohashcash",
+			bodyKey:    []string{"free message"},
+		},
+	)
+	if status != http.StatusOK {
+		t.Fatalf(
+			"expected 200, got %d: %v", status, result,
+		)
+	}
+
+	if result["id"] == nil || result["id"] == "" {
+		t.Fatal("expected message id")
+	}
+}
+
+func TestChannelHashcashInvalidBitsRange(t *testing.T) {
+	tserver := newTestServer(t)
+	token := tserver.createSession("hcbits_user")
+
+	tserver.sendCommand(token, map[string]any{
+		commandKey: joinCmd, toKey: "#hcbits",
+	})
+
+	_, lastID := tserver.pollMessages(token, 0)
+
+	// Try to set bits to 0 — should fail.
+	tserver.sendCommand(token, map[string]any{
+		commandKey: modeCmd,
+		toKey:      "#hcbits",
+		bodyKey:    []string{"+H", "0"},
+	})
+
+	msgs, _ := tserver.pollMessages(token, lastID)
+
+	if !findNumeric(msgs, "472") {
+		t.Fatalf(
+			"expected ERR_UNKNOWNMODE (472), got %v",
+			msgs,
+		)
+	}
+}
+
+func TestChannelHashcashMissingBitsArg(t *testing.T) {
+	tserver := newTestServer(t)
+	token := tserver.createSession("hcnoarg_user")
+
+	tserver.sendCommand(token, map[string]any{
+		commandKey: joinCmd, toKey: "#hcnoarg",
+	})
+
+	_, lastID := tserver.pollMessages(token, 0)
+
+	// Try to set +H without bits argument.
+	tserver.sendCommand(token, map[string]any{
+		commandKey: modeCmd,
+		toKey:      "#hcnoarg",
+		bodyKey:    []string{"+H"},
+	})
+
+	msgs, _ := tserver.pollMessages(token, lastID)
+
+	if !findNumeric(msgs, "461") {
+		t.Fatalf(
+			"expected ERR_NEEDMOREPARAMS (461), got %v",
+			msgs,
+		)
+	}
+}

internal/handlers/handlers.go

@@ -36,15 +36,21 @@ type Params struct {
 
 const defaultIdleTimeout = 30 * 24 * time.Hour
 
+// spentHashcashTTL is how long spent hashcash tokens are
+// retained for replay prevention. Per issue requirements,
+// this is 1 year.
+const spentHashcashTTL = 365 * 24 * time.Hour
+
 // Handlers manages HTTP request handling.
 type Handlers struct {
-	params        *Params
-	log           *slog.Logger
-	hc            *healthcheck.Healthcheck
-	broker        *broker.Broker
-	hashcashVal   *hashcash.Validator
-	stats         *stats.Tracker
-	cancelCleanup context.CancelFunc
+	params          *Params
+	log             *slog.Logger
+	hc              *healthcheck.Healthcheck
+	broker          *broker.Broker
+	hashcashVal     *hashcash.Validator
+	channelHashcash *hashcash.ChannelValidator
+	stats           *stats.Tracker
+	cancelCleanup   context.CancelFunc
 }
 
 // New creates a new Handlers instance.
@@ -58,12 +64,13 @@ func New(
 	}
 
 	hdlr := &Handlers{ //nolint:exhaustruct // cancelCleanup set in startCleanup
-		params:      &params,
-		log:         params.Logger.Get(),
-		hc:          params.Healthcheck,
-		broker:      broker.New(),
-		hashcashVal: hashcash.NewValidator(resource),
-		stats:       params.Stats,
+		params:          &params,
+		log:             params.Logger.Get(),
+		hc:              params.Healthcheck,
+		broker:          broker.New(),
+		hashcashVal:     hashcash.NewValidator(resource),
+		channelHashcash: hashcash.NewChannelValidator(),
+		stats:           params.Stats,
 	}
 
 	lifecycle.Append(fx.Hook{
@@ -285,4 +292,20 @@ func (hdlr *Handlers) pruneQueuesAndMessages(
 			)
 		}
 	}
+
+	// Prune spent hashcash tokens older than 1 year.
+	hashcashCutoff := time.Now().Add(-spentHashcashTTL)
+
+	pruned, err := hdlr.params.Database.
+		PruneSpentHashcash(ctx, hashcashCutoff)
+	if err != nil {
+		hdlr.log.Error(
+			"spent hashcash pruning failed", "error", err,
+		)
+	} else if pruned > 0 {
+		hdlr.log.Info(
+			"pruned spent hashcash tokens",
+			"deleted", pruned,
+		)
+	}
 }