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>
2026-03-18 03:40:33 +01:00
parent efbd8fe9ff
commit bf4d63bc4d
10 changed files with 1451 additions and 42 deletions
--- a/internal/handlers/api.go
+++ b/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,