feat: per-channel hashcash proof-of-work for PRIVMSG anti-spam

Add per-channel hashcash requirement via MODE +H <bits>. When set,
PRIVMSG to the channel must include a valid hashcash stamp in the
meta.hashcash field bound to the channel name and message body hash.

Server validates stamp format, difficulty, date freshness, channel
binding, body hash binding, and proof-of-work. Spent stamps are
persisted to SQLite with 1-year TTL for replay prevention.

Stamp format: 1:bits:YYMMDD:channel:bodyhash:counter

Changes:
- Schema: add hashcash_bits column to channels, spent_hashcash table
- DB: queries for get/set channel hashcash bits, spent token CRUD
- Hashcash: ChannelValidator, BodyHash, StampHash, MintChannelStamp
- Handlers: validate hashcash on PRIVMSG, MODE +H/-H support
- Pass meta through fanOut chain to store in messages
- Prune spent hashcash tokens in cleanup loop (1-year TTL)
- Client: MintChannelHashcash helper for CLI
- Tests: 12 new channel_test.go + 10 new api_test.go integration tests
- README: document +H mode, stamp format, and usage

internal/handlers/handlers.go

@@ -34,14 +34,20 @@ 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
-	cancelCleanup context.CancelFunc
+	params          *Params
+	log             *slog.Logger
+	hc              *healthcheck.Healthcheck
+	broker          *broker.Broker
+	hashcashVal     *hashcash.Validator
+	channelHashcash *hashcash.ChannelValidator
+	cancelCleanup   context.CancelFunc
 }
 
 // New creates a new Handlers instance.
@@ -55,11 +61,12 @@ 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),
+		params:          &params,
+		log:             params.Logger.Get(),
+		hc:              params.Healthcheck,
+		broker:          broker.New(),
+		hashcashVal:     hashcash.NewValidator(resource),
+		channelHashcash: hashcash.NewChannelValidator(),
 	}
 
 	lifecycle.Append(fx.Hook{
@@ -281,4 +288,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,
+		)
+	}
 }