fix(security): API token strength and brute-force lockout

- Refuse an API token under 24 characters or with whitespace at startup, without echoing it
- Lock an address out for 5 minutes after 10 wrong or missing tokens in 5 minutes (429 with Retry-After)
- Ignore X-Forwarded-For for the lockout, forget idle addresses
- Document both
This commit is contained in:
tgiachi 2026-11-09 20:25:05 +01:00
commit 625d487eca
4 changed files with 298 additions and 1 deletions

View file

@ -213,6 +213,10 @@ lists.example.org lmtp:inet:127.0.0.1:2424
and `Reply-To` come from the header; so a post whose header names someone else (or has no usable `From`, or several
addresses) is held for moderation instead of delivered, with the reason shown to the admin (API, CLI, UI). Let Postfix
reject forged senders too (SPF, DKIM, DMARC checks on inbound mail).
- **API token.** `parsimony serve` refuses a token shorter than 24 characters or containing whitespace
(`openssl rand -hex 24` makes a good one). After 10 wrong or missing tokens within 5 minutes an address is
locked out for 5 minutes (HTTP 429, valid token included). The address is the TCP peer: behind a reverse proxy
every client shares the proxy's address, so rate-limit at the proxy as well.
- The API and the admin UI use one bearer token and no TLS: put them behind a reverse proxy with TLS and keep the `api`
listener private.

View file

@ -28,13 +28,19 @@ type server struct {
store *store.Store
token string
releaser Releaser
lim *limiter
}
// New returns the API handler. Every route except /api/v1/health needs
// "Authorization: Bearer <token>". An empty token rejects all requests.
// rel may be nil: approving held messages then answers 501.
func New(s *store.Store, token string, rel Releaser) http.Handler {
srv := &server{store: s, token: token, releaser: rel}
return newHandler(s, token, rel, time.Now)
}
// newHandler is New with an injectable clock for the tests.
func newHandler(s *store.Store, token string, rel Releaser, now func() time.Time) http.Handler {
srv := &server{store: s, token: token, releaser: rel, lim: newLimiter(now)}
mux := http.NewServeMux()
mux.HandleFunc("GET /api/v1/health", func(w http.ResponseWriter, _ *http.Request) {
writeJSON(w, http.StatusOK, map[string]string{"status": "ok"})
@ -61,12 +67,20 @@ func New(s *store.Store, token string, rel Releaser) http.Handler {
func (s *server) auth(next http.HandlerFunc) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
ip := clientIP(r)
if wait, locked := s.lim.blocked(ip); locked {
w.Header().Set("Retry-After", strconv.Itoa(int((wait+time.Second-1)/time.Second)))
writeError(w, http.StatusTooManyRequests, "too many failed attempts, try again later")
return
}
got, ok := strings.CutPrefix(r.Header.Get("Authorization"), "Bearer ")
if !ok || s.token == "" || subtle.ConstantTimeCompare([]byte(got), []byte(s.token)) != 1 {
s.lim.fail(ip)
w.Header().Set("WWW-Authenticate", `Bearer realm="parsimony"`)
writeError(w, http.StatusUnauthorized, "invalid or missing token")
return
}
s.lim.succeed(ip)
next(w, r)
})
}

97
internal/api/limit.go Normal file
View file

@ -0,0 +1,97 @@
package api
import (
"net"
"net/http"
"sync"
"time"
)
// Brute-force protection for the bearer token: after maxFailures wrong (or missing) tokens within
// failureWindow, an address is locked out for lockout, valid token included.
const (
maxFailures = 10
failureWindow = 5 * time.Minute
lockout = 5 * time.Minute
sweepEvery = time.Minute
)
type attempts struct {
count int
first time.Time
blockedUntil time.Time
}
type limiter struct {
mu sync.Mutex
now func() time.Time
byIP map[string]*attempts
lastSweep time.Time
}
func newLimiter(now func() time.Time) *limiter {
return &limiter{now: now, byIP: map[string]*attempts{}, lastSweep: now()}
}
// blocked reports whether ip is locked out and for how much longer.
func (l *limiter) blocked(ip string) (time.Duration, bool) {
l.mu.Lock()
defer l.mu.Unlock()
if e := l.byIP[ip]; e != nil {
if wait := e.blockedUntil.Sub(l.now()); wait > 0 {
return wait, true
}
}
return 0, false
}
func (l *limiter) fail(ip string) {
l.mu.Lock()
defer l.mu.Unlock()
now := l.now()
l.sweep(now)
e := l.byIP[ip]
if e == nil || now.Sub(e.first) > failureWindow {
e = &attempts{first: now}
l.byIP[ip] = e
}
e.count++
if e.count >= maxFailures {
e.blockedUntil = now.Add(lockout)
}
}
func (l *limiter) succeed(ip string) {
l.mu.Lock()
defer l.mu.Unlock()
delete(l.byIP, ip)
}
// sweep forgets addresses whose failures and lockout are over, so the map cannot grow forever.
func (l *limiter) sweep(now time.Time) {
if now.Sub(l.lastSweep) < sweepEvery {
return
}
l.lastSweep = now
for ip, e := range l.byIP {
if now.Sub(e.first) > failureWindow && !now.Before(e.blockedUntil) {
delete(l.byIP, ip)
}
}
}
func (l *limiter) size() int {
l.mu.Lock()
defer l.mu.Unlock()
return len(l.byIP)
}
// clientIP is the address of the TCP peer. X-Forwarded-For is deliberately ignored: anyone can
// send it, so trusting it would let an attacker choose a fresh identity for every guess.
func clientIP(r *http.Request) string {
host, _, err := net.SplitHostPort(r.RemoteAddr)
if err != nil {
return r.RemoteAddr
}
return host
}

182
internal/api/limit_test.go Normal file
View file

@ -0,0 +1,182 @@
package api
import (
"net/http"
"net/http/httptest"
"strconv"
"strings"
"sync"
"testing"
"time"
"codeberg.org/squidd/parsimony/internal/store"
)
type clock struct {
mu sync.Mutex
t time.Time
}
func (c *clock) now() time.Time {
c.mu.Lock()
defer c.mu.Unlock()
return c.t
}
func (c *clock) advance(d time.Duration) {
c.mu.Lock()
c.t = c.t.Add(d)
c.mu.Unlock()
}
func limited(t *testing.T) (http.Handler, *clock) {
t.Helper()
s, err := store.Open(":memory:")
if err != nil {
t.Fatal(err)
}
t.Cleanup(func() { s.Close() })
clk := &clock{t: time.Unix(2_000_000_000, 0)}
return newHandler(s, token, nil, clk.now), clk
}
func attempt(h http.Handler, ip, bearer string) *httptest.ResponseRecorder {
req := httptest.NewRequest("GET", "/api/v1/lists", nil)
req.RemoteAddr = ip + ":40000"
if bearer != "" {
req.Header.Set("Authorization", "Bearer "+bearer)
}
rec := httptest.NewRecorder()
h.ServeHTTP(rec, req)
return rec
}
func TestTooManyWrongTokensLockTheAddressOut(t *testing.T) {
h, _ := limited(t)
for i := 0; i < maxFailures; i++ {
if rec := attempt(h, "203.0.113.7", "wrong"+strconv.Itoa(i)); rec.Code != 401 {
t.Fatalf("attempt %d: %d", i+1, rec.Code)
}
}
rec := attempt(h, "203.0.113.7", token) // even the right token is refused while locked out
if rec.Code != 429 {
t.Fatalf("locked out: status %d", rec.Code)
}
secs, err := strconv.Atoi(rec.Header().Get("Retry-After"))
if err != nil || secs < 1 || secs > int(lockout/time.Second) {
t.Fatalf("Retry-After = %q", rec.Header().Get("Retry-After"))
}
if !strings.Contains(rec.Body.String(), "too many") {
t.Fatalf("body: %s", rec.Body.String())
}
// Other addresses are not affected.
if rec := attempt(h, "203.0.113.8", token); rec.Code != 200 {
t.Fatalf("another address: %d", rec.Code)
}
}
func TestTheLockoutEnds(t *testing.T) {
h, clk := limited(t)
for i := 0; i < maxFailures; i++ {
attempt(h, "203.0.113.7", "wrong")
}
clk.advance(lockout - time.Second)
if rec := attempt(h, "203.0.113.7", token); rec.Code != 429 {
t.Fatalf("still locked: %d", rec.Code)
}
clk.advance(2 * time.Second)
if rec := attempt(h, "203.0.113.7", token); rec.Code != 200 {
t.Fatalf("after the lockout: %d", rec.Code)
}
}
func TestASuccessClearsTheCountAndOldFailuresExpire(t *testing.T) {
h, clk := limited(t)
for i := 0; i < maxFailures-1; i++ {
attempt(h, "203.0.113.7", "wrong")
}
if rec := attempt(h, "203.0.113.7", token); rec.Code != 200 {
t.Fatal("under the limit the right token works")
}
for i := 0; i < maxFailures-1; i++ { // a fresh allowance after a success
attempt(h, "203.0.113.7", "wrong")
}
if rec := attempt(h, "203.0.113.7", token); rec.Code != 200 {
t.Fatalf("a success resets the count: %d", rec.Code)
}
for i := 0; i < maxFailures-1; i++ {
attempt(h, "203.0.113.7", "wrong")
}
clk.advance(failureWindow + time.Second) // the failures are old news
for i := 0; i < maxFailures-1; i++ {
attempt(h, "203.0.113.7", "wrong")
}
if rec := attempt(h, "203.0.113.7", token); rec.Code != 200 {
t.Fatalf("failures older than the window do not add up: %d", rec.Code)
}
}
func TestMissingTokensCountAndHealthDoesNot(t *testing.T) {
h, _ := limited(t)
for i := 0; i < maxFailures; i++ {
health := httptest.NewRequest("GET", "/api/v1/health", nil)
health.RemoteAddr = "203.0.113.7:1"
rec := httptest.NewRecorder()
h.ServeHTTP(rec, health)
if rec.Code != 200 {
t.Fatalf("health: %d", rec.Code)
}
attempt(h, "203.0.113.7", "") // no Authorization header at all
}
if rec := attempt(h, "203.0.113.7", token); rec.Code != 429 {
t.Fatalf("probing without a token adds up too: %d", rec.Code)
}
}
func TestForwardedForHeadersCannotEvadeTheLimit(t *testing.T) {
h, _ := limited(t)
for i := 0; i < maxFailures+3; i++ {
req := httptest.NewRequest("GET", "/api/v1/lists", nil)
req.RemoteAddr = "203.0.113.7:1"
req.Header.Set("X-Forwarded-For", "198.51.100."+strconv.Itoa(i))
req.Header.Set("Authorization", "Bearer wrong")
h.ServeHTTP(httptest.NewRecorder(), req)
}
if rec := attempt(h, "203.0.113.7", token); rec.Code != 429 {
t.Fatalf("a spoofed header must not give a fresh allowance: %d", rec.Code)
}
}
func TestAnEmptyServerTokenStillCountsFailures(t *testing.T) {
s, _ := store.Open(":memory:")
defer s.Close()
h := newHandler(s, "", nil, time.Now)
for i := 0; i < maxFailures; i++ {
req := httptest.NewRequest("GET", "/api/v1/lists", nil)
req.RemoteAddr = "203.0.113.7:1"
req.Header.Set("Authorization", "Bearer ")
h.ServeHTTP(httptest.NewRecorder(), req)
}
req := httptest.NewRequest("GET", "/api/v1/lists", nil)
req.RemoteAddr = "203.0.113.7:1"
rec := httptest.NewRecorder()
h.ServeHTTP(rec, req)
if rec.Code != 429 {
t.Fatalf("%d", rec.Code)
}
}
func TestTheLimiterForgetsOldAddresses(t *testing.T) {
s, _ := store.Open(":memory:")
defer s.Close()
clk := &clock{t: time.Unix(2_000_000_000, 0)}
l := newLimiter(clk.now)
for i := 0; i < 5000; i++ {
l.fail("10.0." + strconv.Itoa(i/250) + "." + strconv.Itoa(i%250))
}
clk.advance(failureWindow + lockout + time.Second)
l.fail("192.0.2.1") // the next failure sweeps expired entries
if n := l.size(); n > 10 {
t.Fatalf("the limiter keeps %d expired addresses: memory grows without bound", n)
}
}