@johnnyboy11234/esg-idea-contest 0.3.0 → 0.3.1

package/backend/internal/auth/internal/store/login_attempt.go

@@ -0,0 +1,53 @@
+package store
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"fmt"
+	"time"
+)
+
+// IPPolicy is the per-IP sliding-window rule (PRD §6.5).
+type IPPolicy struct {
+	MaxFailures   int
+	WindowSeconds int
+}
+
+// RecordIPFailure stores one failed attempt of ip at database time.
+func RecordIPFailure(ctx context.Context, db *sql.DB, ip string) error {
+	if _, err := db.ExecContext(ctx,
+		`INSERT INTO login_attempt (ip, attempted_at) VALUES (?, NOW(6))`, ip); err != nil {
+		return fmt.Errorf("record login attempt: %w", err)
+	}
+	return nil
+}
+
+// IPRetryAfter returns how long ip stays over the limit, 0 when it is not.
+// The address is over the limit while at least MaxFailures failures lie inside
+// the window; it is free again when the MaxFailures-th newest one leaves it,
+// so that row's age decides (with exactly MaxFailures rows this is the oldest).
+func IPRetryAfter(ctx context.Context, db *sql.DB, ip string, p IPPolicy) (time.Duration, error) {
+	var us int64
+	err := db.QueryRowContext(ctx,
+		`SELECT TIMESTAMPDIFF(MICROSECOND, NOW(6), attempted_at + INTERVAL ? SECOND)
+		   FROM login_attempt
+		  WHERE ip = ? AND attempted_at > NOW(6) - INTERVAL ? SECOND
+		  ORDER BY attempted_at DESC
+		  LIMIT 1 OFFSET ?`, p.WindowSeconds, ip, p.WindowSeconds, p.MaxFailures-1).Scan(&us)
+	if errors.Is(err, sql.ErrNoRows) {
+		return 0, nil
+	}
+	if err != nil {
+		return 0, fmt.Errorf("read login attempts: %w", err)
+	}
+	return time.Duration(us) * time.Microsecond, nil
+}
+
+// DeleteOldAttempts removes at most limit login_attempt rows outside the
+// window; IPRetryAfter only reads rows inside it.
+func DeleteOldAttempts(ctx context.Context, db *sql.DB, p IPPolicy, limit int) (int64, error) {
+	return deleteRows(ctx, db, "purge login attempts",
+		`DELETE FROM login_attempt WHERE attempted_at <= NOW(6) - INTERVAL ? SECOND LIMIT ?`,
+		p.WindowSeconds, limit)
+}

package/backend/internal/auth/internal/store/login_lock.go

@@ -0,0 +1,77 @@
+package store
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"fmt"
+	"time"
+)
+
+// LockPolicy is the key-lock rule (PRD §6.5), in seconds and failures.
+type LockPolicy struct {
+	MaxFailures   int
+	WindowSeconds int // a failure older than this no longer counts as consecutive
+	LockSeconds   int // fixed lock length
+}
+
+// RecordFailure counts one failed attempt for key in ONE statement on database
+// time. The assignments run left to right in MariaDB, so later columns see the
+// new fail_count. A lock that is still active is never extended or re-counted
+// (a concurrent attempt that passed Check before the lock was set); an expired
+// lock or a stale window starts again at 1.
+func RecordFailure(ctx context.Context, db *sql.DB, key string, p LockPolicy) error {
+	_, err := db.ExecContext(ctx,
+		`INSERT INTO login_lock (lock_key, fail_count, last_fail_at, locked_until)
+		 VALUES (?, 1, NOW(6), NULL)
+		 ON DUPLICATE KEY UPDATE
+		   fail_count = IF(locked_until > NOW(6), fail_count,
+		                   IF(locked_until IS NOT NULL OR last_fail_at <= NOW(6) - INTERVAL ? SECOND, 1, fail_count + 1)),
+		   locked_until = CASE WHEN locked_until > NOW(6) THEN locked_until
+		                       WHEN fail_count >= ? THEN NOW(6) + INTERVAL ? SECOND
+		                       ELSE NULL END,
+		   last_fail_at = NOW(6)`,
+		key, p.WindowSeconds, p.MaxFailures, p.LockSeconds)
+	if err != nil {
+		return fmt.Errorf("record login failure: %w", err)
+	}
+	return nil
+}
+
+// LockRemaining returns how long key stays locked, 0 when it is not locked.
+func LockRemaining(ctx context.Context, db *sql.DB, key string) (time.Duration, error) {
+	var us sql.NullInt64
+	err := db.QueryRowContext(ctx,
+		`SELECT TIMESTAMPDIFF(MICROSECOND, NOW(6), locked_until)
+		   FROM login_lock WHERE lock_key = ? AND locked_until > NOW(6)`, key).Scan(&us)
+	if errors.Is(err, sql.ErrNoRows) {
+		return 0, nil
+	}
+	if err != nil {
+		return 0, fmt.Errorf("read login lock: %w", err)
+	}
+	return time.Duration(us.Int64) * time.Microsecond, nil
+}
+
+// ClearFailures resets the counter after a successful login. An active lock is
+// left alone (a success cannot shorten it).
+func ClearFailures(ctx context.Context, db *sql.DB, key string) error {
+	_, err := db.ExecContext(ctx,
+		`DELETE FROM login_lock WHERE lock_key = ? AND (locked_until IS NULL OR locked_until <= NOW(6))`, key)
+	if err != nil {
+		return fmt.Errorf("clear login failures: %w", err)
+	}
+	return nil
+}
+
+// DeleteStaleLocks removes at most limit login_lock rows that no longer
+// matter: no active lock and the last failure outside the window. For such a
+// row RecordFailure would start again at 1, exactly as for a missing row.
+func DeleteStaleLocks(ctx context.Context, db *sql.DB, p LockPolicy, limit int) (int64, error) {
+	return deleteRows(ctx, db, "purge login locks",
+		`DELETE FROM login_lock
+		  WHERE last_fail_at <= NOW(6) - INTERVAL ? SECOND
+		    AND (locked_until IS NULL OR locked_until <= NOW(6))
+		  LIMIT ?`,
+		p.WindowSeconds, limit)
+}

package/backend/internal/auth/internal/store/login_throttle_audit.go

@@ -0,0 +1,42 @@
+package store
+
+import (
+	"context"
+	"database/sql"
+	"fmt"
+	"time"
+)
+
+// ClaimThrottleAudit reports whether the caller may write the THROTTLED audit
+// row of (scope, subject): true for the first throttled attempt of a window,
+// false while an earlier claim is still running. A winning claim holds until
+// database now + hold. The claim is atomic, so concurrent attempts on several
+// replicas produce exactly one winner.
+func ClaimThrottleAudit(ctx context.Context, db *sql.DB, scope, subject string, hold time.Duration) (bool, error) {
+	us := hold.Microseconds()
+	res, err := db.ExecContext(ctx,
+		`UPDATE login_throttle_audit SET audited_until = NOW(6) + INTERVAL ? MICROSECOND
+		  WHERE scope = ? AND subject = ? AND audited_until <= NOW(6)`, us, scope, subject)
+	if err != nil {
+		return false, fmt.Errorf("claim throttle audit: %w", err)
+	}
+	if n, _ := res.RowsAffected(); n > 0 {
+		return true, nil
+	}
+	res, err = db.ExecContext(ctx,
+		`INSERT IGNORE INTO login_throttle_audit (scope, subject, audited_until)
+		 VALUES (?, ?, NOW(6) + INTERVAL ? MICROSECOND)`, scope, subject, us)
+	if err != nil {
+		return false, fmt.Errorf("claim throttle audit: %w", err)
+	}
+	n, _ := res.RowsAffected()
+	return n > 0, nil
+}
+
+// DeleteExpiredThrottleAudits removes at most limit claims that have run out.
+// ClaimThrottleAudit treats a missing row like an expired one (the next
+// throttled attempt wins), so deleting it changes no outcome.
+func DeleteExpiredThrottleAudits(ctx context.Context, db *sql.DB, limit int) (int64, error) {
+	return deleteRows(ctx, db, "purge throttle audits",
+		`DELETE FROM login_throttle_audit WHERE audited_until <= NOW(6) LIMIT ?`, limit)
+}

package/backend/internal/auth/internal/store/session.go

@@ -99,19 +99,27 @@ func DeleteByUser(ctx context.Context, db *sql.DB, userID uuid.UUID) error {
 	return nil
 }
 
-// DeleteExpired removes sessions past either timeout and returns how many.
-func DeleteExpired(ctx context.Context, db *sql.DB, l Limits) (int64, error) {
-	res, err := db.ExecContext(ctx,
+// DeleteExpired removes at most limit sessions past either timeout and
+// returns how many. The condition is the exact complement of Touch's, so a row
+// it deletes could no longer be validated anyway.
+func DeleteExpired(ctx context.Context, db *sql.DB, l Limits, limit int) (int64, error) {
+	return deleteRows(ctx, db, "purge sessions",
 		`DELETE FROM session
 		  WHERE last_access_at <= NOW(6) - INTERVAL ? SECOND
-		     OR created_at     <= NOW(6) - INTERVAL ? SECOND`,
-		l.IdleSeconds, l.AbsoluteSeconds)
+		     OR created_at     <= NOW(6) - INTERVAL ? SECOND
+		  LIMIT ?`,
+		l.IdleSeconds, l.AbsoluteSeconds, limit)
+}
+
+// deleteRows runs one DELETE and returns the affected row count.
+func deleteRows(ctx context.Context, db *sql.DB, what, query string, args ...any) (int64, error) {
+	res, err := db.ExecContext(ctx, query, args...)
 	if err != nil {
-		return 0, fmt.Errorf("purge sessions: %w", err)
+		return 0, fmt.Errorf("%s: %w", what, err)
 	}
 	n, err := res.RowsAffected()
 	if err != nil {
-		return 0, fmt.Errorf("purge sessions rows: %w", err)
+		return 0, fmt.Errorf("%s rows: %w", what, err)
 	}
 	return n, nil
 }

package/backend/internal/auth/login.go

@@ -33,15 +33,20 @@ const (
 
 var empNoFormat = regexp.MustCompile(`^[0-9]{6}$`)
 
-// Throttle is the login throttling hook (PRD §6.5). B1b-04 implements it on
-// login_lock / login_attempt; until then NoThrottle is wired. Errors fail the
-// login closed (500): an unreachable counter must not disable the limit.
+// Throttle is the login throttling hook (PRD §6.5); DBThrottle implements it on
+// login_lock. Errors fail the login closed (500): an unreachable counter must
+// not disable the limit.
 type Throttle interface {
 	// Check runs before any password work. A positive retryAfter means the
 	// attempt is throttled: it answers 429, runs no bcrypt and is not counted.
 	// key is the submitted employee-ID string as typed; implementations strip
 	// control characters and cut it to 32 characters.
 	Check(ctx context.Context, key string, ip netip.Addr) (retryAfter time.Duration, err error)
+	// AuditOnce is asked after Check reported a wait. It returns true for the
+	// first throttled attempt of a window and false for the rest, so a throttled
+	// key or address is audited once per window (PRD §6.11). Its error is not
+	// fatal: the attempt is audited anyway.
+	AuditOnce(ctx context.Context, key string, ip netip.Addr) (bool, error)
 	// Fail counts one failed attempt (also for unknown accounts).
 	Fail(ctx context.Context, key string, ip netip.Addr) error
 	// Succeed clears the key's counter.
@@ -54,6 +59,9 @@ type NoThrottle struct{}
 // Check implements Throttle.
 func (NoThrottle) Check(context.Context, string, netip.Addr) (time.Duration, error) { return 0, nil }
 
+// AuditOnce implements Throttle.
+func (NoThrottle) AuditOnce(context.Context, string, netip.Addr) (bool, error) { return true, nil }
+
 // Fail implements Throttle.
 func (NoThrottle) Fail(context.Context, string, netip.Addr) error { return nil }
 
@@ -122,7 +130,11 @@ func (l *Logins) Login(ctx context.Context, cmd LoginCommand, req Request) (Logg
 	if retry > 0 {
 		e := web.NewError(web.CodeLoginThrottled, "too many login attempts")
 		e.RetryAfter = retry
-		return LoggedIn{}, loginRefused(e, audit.Throttled, "throttled", cmd.EmpNo)
+		if first, err := l.Throttle.AuditOnce(ctx, cmd.EmpNo, req.IP); err != nil || first {
+			// An error audits anyway: a duplicate row beats a missing one.
+			return LoggedIn{}, loginRefused(e, audit.Throttled, "throttled", cmd.EmpNo)
+		}
+		return LoggedIn{}, e
 	}
 
 	var (

package/backend/internal/auth/login_integration_test.go

@@ -42,6 +42,9 @@ func (f *fakeThrottle) Check(_ context.Context, key string, _ netip.Addr) (time.
 	f.lastKey = key
 	return f.retry, f.err
 }
+func (f *fakeThrottle) AuditOnce(context.Context, string, netip.Addr) (bool, error) {
+	return true, nil
+}
 func (f *fakeThrottle) Fail(context.Context, string, netip.Addr) error {
 	f.mu.Lock()
 	defer f.mu.Unlock()
@@ -67,13 +70,23 @@ func newLoginEnv(t *testing.T) loginEnv {
 }
 
 func newLoginEnvLog(t *testing.T, log *slog.Logger) loginEnv {
+	t.Helper()
+	return newLoginEnvWith(t, log, nil)
+}
+
+// newLoginEnvWith wires mk(db) as the throttle; nil keeps the fake.
+func newLoginEnvWith(t *testing.T, log *slog.Logger, mk func(*sql.DB) auth.Throttle) loginEnv {
 	t.Helper()
 	db := dbtest.New(t)
 	auditSvc := audit.New(db, nil)
 	errs := server.ErrorAdapter{Audit: auditSvc}
 	sessions := auth.New(db)
 	th := &fakeThrottle{}
-	logins, err := auth.NewLogins(sessions, auditSvc, th)
+	var thr auth.Throttle = th
+	if mk != nil {
+		thr = mk(db)
+	}
+	logins, err := auth.NewLogins(sessions, auditSvc, thr)
 	if err != nil {
 		t.Fatal(err)
 	}

package/backend/internal/auth/login_ip_integration_test.go

@@ -0,0 +1,153 @@
+//go:build integration
+
+package auth_test
+
+import (
+	"net/http/httptest"
+	"strconv"
+	"strings"
+	"testing"
+
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/shared/web"
+)
+
+// loginFrom posts a login as peer ip (TCP address) with each empNo of its own
+// so that the key lock never interferes with the IP window.
+func (e loginEnv) loginFrom(t *testing.T, ip, empNo, pw string, hdr map[string]string) *httptest.ResponseRecorder {
+	t.Helper()
+	tok, ck := e.csrf(t, nil)
+	req := httptest.NewRequest("POST", "/api/v1/auth/login", strings.NewReader(creds(empNo, pw)))
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("X-CSRF-Token", tok)
+	req.RemoteAddr = ip + ":4000"
+	req.AddCookie(ck)
+	for k, v := range hdr {
+		req.Header.Set(k, v)
+	}
+	return e.do(req)
+}
+
+func (e loginEnv) ipFailures(t *testing.T, ip string) (n int) {
+	t.Helper()
+	if err := e.db.QueryRow(`SELECT COUNT(*) FROM login_attempt WHERE ip = ?`, ip).Scan(&n); err != nil {
+		t.Fatal(err)
+	}
+	return n
+}
+
+// seed inserts n failures of ip, all age seconds old, without running logins
+// (a real failure costs a bcrypt comparison, ~1 s under -race).
+func (e loginEnv) seed(t *testing.T, ip string, n, ageSeconds int) {
+	t.Helper()
+	for range n {
+		if _, err := e.db.Exec(`INSERT INTO login_attempt (ip, attempted_at) VALUES (?, NOW(6) - INTERVAL ? SECOND)`, ip, ageSeconds); err != nil {
+			t.Fatal(err)
+		}
+	}
+}
+
+func TestLoginIP30thFailureIs401And31stIs429(t *testing.T) {
+	e := newLockEnv(t)
+	e.seed(t, "192.0.2.9", 29, 0)
+	// The 30th failure is a real login: still 401, and it is recorded.
+	if rec := e.loginFrom(t, "192.0.2.9", "100000", wrongPassword, nil); rec.Code != 401 {
+		t.Fatalf("30th: %d %s", rec.Code, rec.Body)
+	}
+	if n := e.ipFailures(t, "192.0.2.9"); n != 30 {
+		t.Fatalf("rows = %d", n)
+	}
+	rec := e.loginFrom(t, "192.0.2.9", "999999", wrongPassword, nil)
+	if rec.Code != 429 || code(t, rec) != "LOGIN_THROTTLED" {
+		t.Fatalf("31st: %d %s", rec.Code, rec.Body)
+	}
+	if got, _ := strconv.Atoi(rec.Header().Get("Retry-After")); got < 895 || got > 900 {
+		t.Errorf("Retry-After = %q, want ~900", rec.Header().Get("Retry-After"))
+	}
+	// Throttled attempts are not counted, for the IP or the key.
+	if n := e.ipFailures(t, "192.0.2.9"); n != 30 {
+		t.Errorf("rows after throttled attempt = %d", n)
+	}
+	if n, _ := e.lockRow(t, "999999"); n != 0 {
+		t.Errorf("key counted: %d", n)
+	}
+}
+
+func TestLoginIPCorrectPasswordIsThrottledToo(t *testing.T) {
+	e := newLockEnv(t)
+	e.addUser(t, "123456", "ADMIN", true)
+	e.seed(t, "192.0.2.9", 30, 0)
+	if rec := e.loginFrom(t, "192.0.2.9", "123456", password, nil); rec.Code != 429 {
+		t.Fatalf("admin from throttled IP: %d %s", rec.Code, rec.Body)
+	}
+	if rec := e.loginFrom(t, "192.0.2.10", "123456", password, nil); rec.Code != 200 {
+		t.Fatalf("other IP: %d %s", rec.Code, rec.Body)
+	}
+}
+
+func TestLoginIPWindowSlides(t *testing.T) {
+	e := newLockEnv(t)
+	e.seed(t, "192.0.2.9", 1, 14*60) // oldest: leaves the window in ~1 min
+	e.seed(t, "192.0.2.9", 29, 60)
+	rec := e.loginFrom(t, "192.0.2.9", "999999", wrongPassword, nil)
+	if rec.Code != 429 {
+		t.Fatalf("30 in window: %d", rec.Code)
+	}
+	if got, _ := strconv.Atoi(rec.Header().Get("Retry-After")); got < 50 || got > 61 {
+		t.Errorf("Retry-After = %d, want ~60 (oldest leaves in 1 min)", got)
+	}
+	// Push the oldest out: 29 in the window, so the next attempt is allowed (and counted).
+	if _, err := e.db.Exec(`UPDATE login_attempt SET attempted_at = attempted_at - INTERVAL 2 MINUTE ORDER BY attempted_at LIMIT 1`); err != nil {
+		t.Fatal(err)
+	}
+	if rec := e.loginFrom(t, "192.0.2.9", "999999", wrongPassword, nil); rec.Code != 401 {
+		t.Fatalf("29 in window: %d %s", rec.Code, rec.Body)
+	}
+	if rec := e.loginFrom(t, "192.0.2.9", "999998", wrongPassword, nil); rec.Code != 429 {
+		t.Fatalf("back to 30: %d", rec.Code)
+	}
+}
+
+// With more than 30 rows the wait is until the 30th newest leaves, not the oldest.
+func TestLoginIPRetryAfterUsesThirtiethNewest(t *testing.T) {
+	e := newLockEnv(t)
+	e.seed(t, "192.0.2.9", 5, 14*60) // five old ones
+	e.seed(t, "192.0.2.9", 30, 10)   // 30 recent: the 30th newest is 10 s old
+	rec := e.loginFrom(t, "192.0.2.9", "999999", wrongPassword, nil)
+	if got, _ := strconv.Atoi(rec.Header().Get("Retry-After")); rec.Code != 429 || got < 880 || got > 891 {
+		t.Fatalf("%d Retry-After=%q, want ~890", rec.Code, rec.Header().Get("Retry-After"))
+	}
+}
+
+func TestLoginIPLimitIsPerAddress(t *testing.T) {
+	e := newLockEnv(t)
+	e.seed(t, "192.0.2.9", 30, 0)
+	e.seed(t, "2001:db8::1", 5, 0)
+	if rec := e.loginFrom(t, "2001:db8::1", "999999", wrongPassword, nil); rec.Code != 401 {
+		t.Fatalf("other address: %d", rec.Code)
+	}
+}
+
+func TestLoginIPUsesForwardedClientWhenTrusted(t *testing.T) {
+	e := newLockEnv(t)
+	e.h = web.TrustedProxies(1)(e.h)
+	hdr := map[string]string{"X-Forwarded-For": "10.9.9.9, 198.51.100.1"}
+	if rec := e.loginFrom(t, "192.0.2.9", "100000", wrongPassword, hdr); rec.Code != 401 {
+		t.Fatalf("failure: %d", rec.Code)
+	}
+	if n := e.ipFailures(t, "198.51.100.1"); n != 1 || e.ipFailures(t, "192.0.2.9") != 0 || e.ipFailures(t, "10.9.9.9") != 0 {
+		t.Fatalf("failure not recorded for the forwarded client only")
+	}
+	e.seed(t, "198.51.100.1", 29, 0)
+	if rec := e.loginFrom(t, "192.0.2.9", "999999", wrongPassword, hdr); rec.Code != 429 {
+		t.Fatalf("forwarded client not throttled: %d", rec.Code)
+	}
+	// Changing the spoofable prefix does not help; another proxy peer with another client is free.
+	if rec := e.loginFrom(t, "192.0.2.9", "999999", wrongPassword,
+		map[string]string{"X-Forwarded-For": "1.1.1.1, 198.51.100.1"}); rec.Code != 429 {
+		t.Fatalf("spoofed prefix: %d", rec.Code)
+	}
+	if rec := e.loginFrom(t, "192.0.2.9", "999999", wrongPassword,
+		map[string]string{"X-Forwarded-For": "198.51.100.2"}); rec.Code != 401 {
+		t.Fatalf("other client: %d", rec.Code)
+	}
+}

package/backend/internal/auth/login_lock_integration_test.go

@@ -0,0 +1,205 @@
+//go:build integration
+
+package auth_test
+
+import (
+	"database/sql"
+	"log/slog"
+	"strings"
+	"testing"
+
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/auth"
+)
+
+const wrongPassword = "Wrong-Horse-9"
+
+func newLockEnv(t *testing.T) loginEnv {
+	t.Helper()
+	return newLoginEnvWith(t, slog.New(slog.DiscardHandler), func(db *sql.DB) auth.Throttle { return auth.DBThrottle{DB: db} })
+}
+
+func (e loginEnv) fail(t *testing.T, empNo string) {
+	t.Helper()
+	if rec := e.login(t, creds(empNo, wrongPassword)); rec.Code != 401 {
+		t.Fatalf("failure attempt: %d %s", rec.Code, rec.Body)
+	}
+}
+
+func (e loginEnv) lockRow(t *testing.T, key string) (count int, locked bool) {
+	t.Helper()
+	err := e.db.QueryRow(`SELECT fail_count, COALESCE(locked_until > NOW(6), 0) FROM login_lock WHERE lock_key = ?`, key).Scan(&count, &locked)
+	if err == sql.ErrNoRows {
+		return 0, false
+	}
+	if err != nil {
+		t.Fatal(err)
+	}
+	return count, locked
+}
+
+// ageLock moves the key's lock state back by d minutes (time passing, DB clock).
+func (e loginEnv) ageLock(t *testing.T, key string, minutes int) {
+	t.Helper()
+	if _, err := e.db.Exec(`UPDATE login_lock SET last_fail_at = last_fail_at - INTERVAL ? MINUTE,
+		locked_until = locked_until - INTERVAL ? MINUTE WHERE lock_key = ?`, minutes, minutes, key); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestLoginLockFifthFailureIs401SixthIs429(t *testing.T) {
+	e := newLockEnv(t)
+	e.addUser(t, "123456", "USER", true)
+	for range 5 {
+		e.fail(t, "123456")
+	}
+	if n, locked := e.lockRow(t, "123456"); n != 5 || !locked {
+		t.Fatalf("after 5th failure: count=%d locked=%v", n, locked)
+	}
+	rec := e.login(t, creds("123456", wrongPassword))
+	if rec.Code != 429 || code(t, rec) != "LOGIN_THROTTLED" {
+		t.Fatalf("6th attempt: %d %s", rec.Code, rec.Body)
+	}
+	if got := rec.Header().Get("Retry-After"); got != "900" && got != "899" {
+		t.Errorf("Retry-After = %q, want ~900", got)
+	}
+}
+
+func TestLoginLockCorrectPasswordDuringLockIs429AndDoesNotExtend(t *testing.T) {
+	e := newLockEnv(t)
+	e.addUser(t, "123456", "USER", true)
+	for range 5 {
+		e.fail(t, "123456")
+	}
+	e.ageLock(t, "123456", 10) // 5 minutes left
+	var before string
+	if err := e.db.QueryRow(`SELECT locked_until FROM login_lock WHERE lock_key = '123456'`).Scan(&before); err != nil {
+		t.Fatal(err)
+	}
+	for _, pw := range []string{password, wrongPassword} {
+		rec := e.login(t, creds("123456", pw))
+		if rec.Code != 429 {
+			t.Fatalf("during lock with %q: %d %s", pw, rec.Code, rec.Body)
+		}
+		if got := rec.Header().Get("Retry-After"); got != "300" && got != "299" {
+			t.Errorf("Retry-After = %q, want ~300", got)
+		}
+	}
+	var after string
+	if err := e.db.QueryRow(`SELECT locked_until FROM login_lock WHERE lock_key = '123456'`).Scan(&after); err != nil {
+		t.Fatal(err)
+	}
+	if before != after {
+		t.Errorf("lock extended: %s → %s", before, after)
+	}
+	if e.sessions(t) != 0 {
+		t.Error("session opened during lock")
+	}
+}
+
+func TestLoginLockExpiresAfterFifteenMinutes(t *testing.T) {
+	e := newLockEnv(t)
+	e.addUser(t, "123456", "USER", true)
+	for range 5 {
+		e.fail(t, "123456")
+	}
+	e.ageLock(t, "123456", 16)
+	if rec := e.login(t, creds("123456", password)); rec.Code != 200 {
+		t.Fatalf("after lock expiry: %d %s", rec.Code, rec.Body)
+	}
+	if n, _ := e.lockRow(t, "123456"); n != 0 {
+		t.Errorf("counter not cleared by success: %d", n)
+	}
+}
+
+func TestLoginLockCounterRestartsAfterExpiredLock(t *testing.T) {
+	e := newLockEnv(t)
+	e.addUser(t, "123456", "USER", true)
+	for range 5 {
+		e.fail(t, "123456")
+	}
+	e.ageLock(t, "123456", 16)
+	e.fail(t, "123456")
+	if n, locked := e.lockRow(t, "123456"); n != 1 || locked {
+		t.Errorf("count=%d locked=%v, want 1 / unlocked", n, locked)
+	}
+}
+
+func TestLoginLockFailuresMustBeConsecutiveWithinWindow(t *testing.T) {
+	e := newLockEnv(t)
+	e.addUser(t, "123456", "USER", true)
+	for range 4 {
+		e.fail(t, "123456")
+	}
+	e.ageLock(t, "123456", 16) // the 4 failures are stale
+	e.fail(t, "123456")
+	if n, locked := e.lockRow(t, "123456"); n != 1 || locked {
+		t.Errorf("count=%d locked=%v, want 1 / unlocked", n, locked)
+	}
+	// Within the window the count keeps growing.
+	e.ageLock(t, "123456", 14)
+	for range 3 {
+		e.fail(t, "123456")
+	}
+	if n, _ := e.lockRow(t, "123456"); n != 4 {
+		t.Errorf("count = %d, want 4", n)
+	}
+}
+
+func TestLoginLockSuccessClearsCounter(t *testing.T) {
+	e := newLockEnv(t)
+	e.addUser(t, "123456", "USER", true)
+	for range 4 {
+		e.fail(t, "123456")
+	}
+	if rec := e.login(t, creds("123456", password)); rec.Code != 200 {
+		t.Fatalf("%d %s", rec.Code, rec.Body)
+	}
+	for range 4 {
+		e.fail(t, "123456")
+	}
+	if rec := e.login(t, creds("123456", password)); rec.Code != 200 {
+		t.Fatalf("counter not reset by success: %d %s", rec.Code, rec.Body)
+	}
+}
+
+func TestLoginLockCountsUnknownAndMalformedKeys(t *testing.T) {
+	e := newLockEnv(t)
+	for _, key := range []string{"999999", "not-an-id"} {
+		for range 5 {
+			e.fail(t, key)
+		}
+		if rec := e.login(t, creds(key, wrongPassword)); rec.Code != 429 {
+			t.Errorf("%q: 6th attempt = %d, want 429", key, rec.Code)
+		}
+	}
+}
+
+func TestLoginLockIsPerKeyAndDisabledAccountsCount(t *testing.T) {
+	e := newLockEnv(t)
+	e.addUser(t, "123456", "USER", true)
+	e.addUser(t, "654321", "USER", false)
+	for range 5 {
+		e.fail(t, "654321") // disabled: same 401, still counted
+	}
+	if rec := e.login(t, creds("654321", password)); rec.Code != 429 {
+		t.Errorf("disabled key: %d", rec.Code)
+	}
+	if rec := e.login(t, creds("123456", password)); rec.Code != 200 {
+		t.Errorf("other key affected: %d %s", rec.Code, rec.Body)
+	}
+}
+
+func TestLoginLockKeyIsNormalised(t *testing.T) {
+	e := newLockEnv(t)
+	long := strings.Repeat("9", 40)
+	for range 5 {
+		e.fail(t, long)
+	}
+	// Same first 32 characters share the key.
+	if rec := e.login(t, creds(strings.Repeat("9", 32)+"x", wrongPassword)); rec.Code != 429 {
+		t.Errorf("cut key: %d", rec.Code)
+	}
+	if n, _ := e.lockRow(t, strings.Repeat("9", 32)); n != 5 {
+		t.Errorf("count = %d, want 5", n)
+	}
+}

package/backend/internal/auth/login_test.go

@@ -66,3 +66,18 @@ func TestComparePassword(t *testing.T) {
 		}
 	}
 }
+
+func TestLockKey(t *testing.T) {
+	tests := []struct{ in, want string }{
+		{"123456", "123456"},
+		{"12\x00\n34\t56\x7f", "123456"},
+		{strings.Repeat("a", 40), strings.Repeat("a", 32)},
+		{strings.Repeat("工", 33), strings.Repeat("工", 32)},
+		{"", ""},
+	}
+	for _, tc := range tests {
+		if got := LockKey(tc.in); got != tc.want {
+			t.Errorf("LockKey(%q) = %q, want %q", tc.in, got, tc.want)
+		}
+	}
+}