feat: add per-IP rate limiting to login endpoint (#78)

## Summary

Adds per-IP rate limiting to `POST /api/v1/login` to prevent brute-force password attacks.

closes #35

## What Changed

### New package: `internal/ratelimit/`

A generic per-key token-bucket rate limiter built on `golang.org/x/time/rate`:
- `New(ratePerSec, burst)` creates a limiter with automatic background cleanup of stale entries
- `Allow(key)` checks if a request from the given key should be permitted
- `Stop()` terminates the background sweep goroutine
- Stale entries (unused for 15 minutes) are pruned every 10 minutes

### Login handler integration

The login handler (`internal/handlers/auth.go`) now:
1. Extracts the client IP from `X-Forwarded-For`, `X-Real-IP`, or `RemoteAddr`
2. Checks the per-IP rate limiter before processing the login
3. Returns **429 Too Many Requests** with a `Retry-After: 1` header when the limit is exceeded

### Configuration

Two new environment variables (via Viper):

| Variable | Default | Description |
|---|---|---|
| `LOGIN_RATE_LIMIT` | `1` | Allowed login attempts per second per IP |
| `LOGIN_RATE_BURST` | `5` | Maximum burst of login attempts per IP |

### Scope

Per [sneak's instruction](#35), only the login endpoint is rate-limited. Session creation and registration use hashcash proof-of-work instead.

## Tests

- 6 unit tests for the `ratelimit` package (constructor, burst, burst exceeded, key isolation, key tracking, stop)
- 2 integration tests in `api_test.go`:
  - `TestLoginRateLimitExceeded`: exhausts burst with rapid requests, verifies 429 response and `Retry-After` header
  - `TestLoginRateLimitAllowsNormalUse`: verifies normal login still works

## README

- Added "Login Rate Limiting" subsection under "Rate Limiting & Abuse Prevention"
- Added `LOGIN_RATE_LIMIT` and `LOGIN_RATE_BURST` to the Configuration table

Co-authored-by: clawbot <clawbot@noreply.git.eeqj.de>
Reviewed-on: #78
Co-authored-by: clawbot <clawbot@noreply.example.org>
Co-committed-by: clawbot <clawbot@noreply.example.org>

internal/handlers/api_test.go

@@ -2388,6 +2388,109 @@ func TestSessionUsernameDefault(t *testing.T) {
 	_ = token
 }
 
+func TestLoginRateLimitExceeded(t *testing.T) {
+	tserver := newTestServer(t)
+
+	// Exhaust the burst (default: 5 per IP) using
+	// nonexistent users. These fail fast (no bcrypt),
+	// preventing token replenishment between requests.
+	for range 5 {
+		loginBody, mErr := json.Marshal(
+			map[string]string{
+				"nick":     "nosuchuser",
+				"password": "doesnotmatter",
+			},
+		)
+		if mErr != nil {
+			t.Fatal(mErr)
+		}
+
+		loginResp, rErr := doRequest(
+			t,
+			http.MethodPost,
+			tserver.url("/api/v1/login"),
+			bytes.NewReader(loginBody),
+		)
+		if rErr != nil {
+			t.Fatal(rErr)
+		}
+
+		_ = loginResp.Body.Close()
+	}
+
+	// The next request should be rate-limited.
+	loginBody, err := json.Marshal(map[string]string{
+		"nick": "nosuchuser", "password": "doesnotmatter",
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	resp, err := doRequest(
+		t,
+		http.MethodPost,
+		tserver.url("/api/v1/login"),
+		bytes.NewReader(loginBody),
+	)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	defer func() { _ = resp.Body.Close() }()
+
+	if resp.StatusCode != http.StatusTooManyRequests {
+		t.Fatalf(
+			"expected 429, got %d",
+			resp.StatusCode,
+		)
+	}
+
+	retryAfter := resp.Header.Get("Retry-After")
+	if retryAfter == "" {
+		t.Fatal("expected Retry-After header")
+	}
+}
+
+func TestLoginRateLimitAllowsNormalUse(t *testing.T) {
+	tserver := newTestServer(t)
+
+	// Create session and set password via PASS command.
+	token := tserver.createSession("normaluser")
+
+	tserver.sendCommand(token, map[string]any{
+		commandKey: "PASS",
+		bodyKey:    []string{"password123"},
+	})
+
+	// A single login should succeed without rate limiting.
+	loginBody, err := json.Marshal(map[string]string{
+		"nick": "normaluser", "password": "password123",
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	resp2, err := doRequest(
+		t,
+		http.MethodPost,
+		tserver.url("/api/v1/login"),
+		bytes.NewReader(loginBody),
+	)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	defer func() { _ = resp2.Body.Close() }()
+
+	if resp2.StatusCode != http.StatusOK {
+		respBody, _ := io.ReadAll(resp2.Body)
+		t.Fatalf(
+			"expected 200, got %d: %s",
+			resp2.StatusCode, respBody,
+		)
+	}
+}
+
 func TestNickBroadcastToChannels(t *testing.T) {
 	tserver := newTestServer(t)
 	aliceToken := tserver.createSession("nick_a")

internal/handlers/auth.go

@@ -28,6 +28,21 @@ func (hdlr *Handlers) handleLogin(
 	writer http.ResponseWriter,
 	request *http.Request,
 ) {
+	ip := clientIP(request)
+
+	if !hdlr.loginLimiter.Allow(ip) {
+		writer.Header().Set(
+			"Retry-After", "1",
+		)
+		hdlr.respondError(
+			writer, request,
+			"too many login attempts, try again later",
+			http.StatusTooManyRequests,
+		)
+
+		return
+	}
+
 	type loginRequest struct {
 		Nick     string `json:"nick"`
 		Password string `json:"password"`
@@ -58,6 +73,16 @@ func (hdlr *Handlers) handleLogin(
 		return
 	}
 
+	hdlr.executeLogin(
+		writer, request, payload.Nick, payload.Password,
+	)
+}
+
+func (hdlr *Handlers) executeLogin(
+	writer http.ResponseWriter,
+	request *http.Request,
+	nick, password string,
+) {
 	remoteIP := clientIP(request)
 
 	hostname := resolveHostname(
@@ -67,8 +92,7 @@ func (hdlr *Handlers) handleLogin(
 	sessionID, clientID, token, err :=
 		hdlr.params.Database.LoginUser(
 			request.Context(),
-			payload.Nick,
-			payload.Password,
+			nick, password,
 			remoteIP, hostname,
 		)
 	if err != nil {
@@ -84,20 +108,20 @@ func (hdlr *Handlers) handleLogin(
 	hdlr.stats.IncrConnections()
 
 	hdlr.deliverMOTD(
-		request, clientID, sessionID, payload.Nick,
+		request, clientID, sessionID, nick,
 	)
 
 	// Initialize channel state so the new client knows
 	// which channels the session already belongs to.
 	hdlr.initChannelState(
-		request, clientID, sessionID, payload.Nick,
+		request, clientID, sessionID, nick,
 	)
 
 	hdlr.setAuthCookie(writer, request, token)
 
 	hdlr.respondJSON(writer, request, map[string]any{
 		"id":   sessionID,
-		"nick": payload.Nick,
+		"nick": nick,
 	}, http.StatusOK)
 }
 

internal/handlers/handlers.go

@@ -16,6 +16,7 @@ import (
 	"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/ratelimit"
 	"git.eeqj.de/sneak/neoirc/internal/stats"
 	"go.uber.org/fx"
 )
@@ -49,6 +50,7 @@ type Handlers struct {
 	broker          *broker.Broker
 	hashcashVal     *hashcash.Validator
 	channelHashcash *hashcash.ChannelValidator
+	loginLimiter    *ratelimit.Limiter
 	stats           *stats.Tracker
 	cancelCleanup   context.CancelFunc
 }
@@ -63,6 +65,16 @@ func New(
 		resource = "neoirc"
 	}
 
+	loginRate := params.Config.LoginRateLimit
+	if loginRate <= 0 {
+		loginRate = ratelimit.DefaultRate
+	}
+
+	loginBurst := params.Config.LoginRateBurst
+	if loginBurst <= 0 {
+		loginBurst = ratelimit.DefaultBurst
+	}
+
 	hdlr := &Handlers{ //nolint:exhaustruct // cancelCleanup set in startCleanup
 		params:          &params,
 		log:             params.Logger.Get(),
@@ -70,6 +82,7 @@ func New(
 		broker:          broker.New(),
 		hashcashVal:     hashcash.NewValidator(resource),
 		channelHashcash: hashcash.NewChannelValidator(),
+		loginLimiter:    ratelimit.New(loginRate, loginBurst),
 		stats:           params.Stats,
 	}
 
@@ -162,6 +175,10 @@ func (hdlr *Handlers) stopCleanup() {
 	if hdlr.cancelCleanup != nil {
 		hdlr.cancelCleanup()
 	}
+
+	if hdlr.loginLimiter != nil {
+		hdlr.loginLimiter.Stop()
+	}
 }
 
 func (hdlr *Handlers) cleanupLoop(ctx context.Context) {