Verify login credentials before spending rate-limit budget (closes #150)

With TRUSTED_PROXIES empty behind the reverse proxy production is
required to run behind, every login POST keyed on the proxy's address
and shared one 5/minute bucket. A stranger sending five POSTs a
minute -- 0.08 requests per second, from anywhere -- kept that bucket
permanently full, and the operator's own correct password was answered
429 indefinitely with no second administrative path.

The login POST no longer has a pre-emptive limiter. The handler
verifies credentials first and spends budget only on a FAILED attempt,
so a correct password is never throttled whatever the counters hold.
Three things follow, and are implemented together because the first is
unsafe without the other two:

- Failures are counted per (client bucket, submitted username), five
  per minute, after which further failures get 429 with a Retry-After.
  A successful login clears the counter, so mistyping and then
  succeeding does not leave the operator throttled.
- Both key sets are capped at 1024 entries. The submitted username is
  attacker-controlled, so past the first cap failures fall back to a
  counter keyed on the client alone, and past both caps a failure is
  answered as throttled without being recorded. Tracked state stays
  under half a megabyte and does not grow with invented usernames.
- Concurrent Argon2id verifications are capped at two, a 128 MB
  ceiling at 64 MB per hash, and the queue for those slots is capped
  at 64 waiters. Every password-hashing endpoint takes a slot,
  including the password-change endpoint, which holds one across both
  its hashes. A request that waits five seconds without a slot is
  answered 503, and one that arrives with the queue already full is
  shed with 503 immediately rather than joining it. Bounding the wait
  alone would not bound memory: a waiter reaches the guard with its
  form parsed, so it holds up to the 1 MB body cap for the whole wait,
  and at flood rates an unbounded queue is worth gigabytes against a
  128 MB hashing budget. 64 waiters is 64 MB of committed queue
  memory, shallow enough that two slots drain a full queue inside the
  five-second deadline; peak commitment is 128 MB of hashing plus
  about 66 MB of parsed bodies.

An unknown username is verified against a dummy hash instead of
returning early, so a nonexistent account costs the same time as a
real one and the response cannot be used to enumerate usernames.

The password-change limiter is unchanged: RequireAuth runs ahead of
it, so only a request already carrying a valid session reaches its
bucket.

Two consequences are documented rather than fixed, because they follow
from the shape the issue asks for. Online guessing throughput rises
from 5 a minute to roughly 27 a second, about 2.3 million a day: the
credential check always precedes the counter, so the 429 is a label on
the response rather than a gate in front of the hash, and what bounds
brute force is the semaphore. And under a sustained flood the residual
exposure is a loss of login availability, not merely of latency --
above about 27 requests a second most attempts are shed with 503, so a
determined flood still denies login for as long as it runs. It costs
roughly 400x more to run, nothing accumulates, and the first attempt
after it stops succeeds. Restarting the service does not help: the
counters a restart clears are not what is saturated.

Also adds the missing test for the third bucketKey call site, where
the peer is a trusted proxy but the forwarded chain names no client.
Every existing test of that fallback uses an IPv4 proxy, where
bucketKey is the identity function, so dropping the /64 masking there
left the suite green.

README and the TRUSTED_PROXIES startup warning updated: a shared
bucket now costs precision, not the availability of the admin path.

internal/database/export_test.go

@@ -65,3 +65,9 @@ func (r *RetentionReaper) ExportWedgeLoop(
 func (r *RetentionReaper) ExportSetInterval(d time.Duration) {
 	r.interval = d
 }
+
+// DummyPasswordHashForTest exposes the encoded hash that unknown
+// usernames are verified against.
+func DummyPasswordHashForTest() string {
+	return dummyPasswordHash()
+}

internal/database/password.go

@@ -8,6 +8,7 @@ import (
 	"fmt"
 	"math/big"
 	"strings"
+	"sync"
 
 	"golang.org/x/crypto/argon2"
 )
@@ -29,6 +30,10 @@ const hashParts = 6
 // triggers per-character-class complexity enforcement.
 const minPasswordComplexityLen = 4
 
+// dummyPasswordLen is the length of the throwaway password behind
+// dummyPasswordHash.
+const dummyPasswordLen = 32
+
 // Sentinel errors returned by decodeHash.
 var (
 	errInvalidHashFormat    = errors.New("invalid hash format")
@@ -122,6 +127,38 @@ func VerifyPassword(
 	return subtle.ConstantTimeCompare(hash, otherHash) == 1, nil
 }
 
+// dummyPasswordHash is an encoded Argon2id hash of a random
+// password, computed once on first use. Nothing can match it: the
+// password it encodes is discarded as soon as it is hashed. It is
+// process-wide because building it per request would add a second
+// 64 MB Argon2id pass to every login for an unknown username.
+//
+//nolint:gochecknoglobals // computed once, see above
+var dummyPasswordHash = sync.OnceValue(func() string {
+	password, err := GenerateRandomPassword(dummyPasswordLen)
+	if err != nil {
+		panic(fmt.Sprintf("generating the dummy password: %v", err))
+	}
+
+	hash, err := HashPassword(password)
+	if err != nil {
+		panic(fmt.Sprintf("hashing the dummy password: %v", err))
+	}
+
+	return hash
+})
+
+// VerifyDummyPassword performs a credential verification that cannot
+// succeed, at the same cost as a real one.
+//
+// Login must charge an unknown username the same work as a known
+// one. Returning early for an account that does not exist answers in
+// microseconds where a real account takes tens of milliseconds, which
+// is a username oracle any client can read off the response time.
+func VerifyDummyPassword(password string) {
+	_, _ = VerifyPassword(password, dummyPasswordHash())
+}
+
 // decodeHash extracts parameters, salt, and hash from an
 // encoded hash string.
 func decodeHash(

internal/database/password_test.go

@@ -191,3 +191,41 @@ func TestHashPasswordUniqueness(t *testing.T) {
 		)
 	}
 }
+
+// TestVerifyDummyPassword_DoesRealWork covers the anti-enumeration
+// path. Login charges an unknown username a verification against a
+// dummy hash so that a nonexistent account is not answered in
+// microseconds where a real one takes tens of milliseconds. That only
+// works if the dummy hash is a real, decodable Argon2id hash: a
+// malformed one would make VerifyPassword fail on the decode and
+// return before hashing anything.
+func TestVerifyDummyPassword_DoesRealWork(t *testing.T) {
+	t.Parallel()
+
+	// Runs the OnceValue that builds the dummy hash, so a panic in
+	// it surfaces here rather than on a live login.
+	database.VerifyDummyPassword("whatever was submitted")
+
+	dummy := database.DummyPasswordHashForTest()
+
+	// A hash the verifier cannot decode would make VerifyPassword
+	// return on the decode error, before hashing anything — the
+	// timing oracle this path exists to close.
+	valid, err := database.VerifyPassword("whatever", dummy)
+	if err != nil {
+		t.Fatalf(
+			"the dummy hash must decode like a real one: %v", err,
+		)
+	}
+
+	if valid {
+		t.Error("nothing may authenticate against the dummy hash")
+	}
+
+	if !strings.HasPrefix(dummy, "$argon2id$") {
+		t.Errorf(
+			"the dummy hash must use the same algorithm as real "+
+				"hashes, got %q", dummy,
+		)
+	}
+}