@nakedev/go-scaffold 0.5.4 → 0.8.0

package/templates/add/auth/internal/app/user/adapters/outbound/postgres/repository.go.hbs

@@ -9,6 +9,7 @@ import (
 
 	"{{goModule}}/internal/app/user/domain"
 	"{{goModule}}/internal/app/user/ports"
+	"{{goModule}}/internal/shared/dbq"
 	"{{goModule}}/internal/shared/dberr"
 	"{{goModule}}/internal/shared/tx"
 
@@ -76,12 +77,39 @@ func (r *Repository) UpdateUser(ctx context.Context, user *domain.User) error {
 	}))
 }
 
-func (r *Repository) FindAll(ctx context.Context, limit, offset int) ([]domain.User, error) {
+// FindAll answers one page of the filter and how many accounts it matched
+// altogether. Two queries for that, because a count over a LIMITed query would
+// only ever count the page.
+func (r *Repository) FindAll(ctx context.Context, filter ports.ListFilter) ([]domain.User, int64, error) {
+	// A closure rather than one *gorm.DB reused twice: conditions accumulate
+	// on the value, so the count would silently inherit the page's LIMIT.
+	matching := func() *gorm.DB {
+		q := tx.From(ctx, r.db).WithContext(ctx).Model(&User{})
+		if filter.Search != "" {
+			// The address lives one table over, so its leg of the OR is a
+			// subquery on user_emails rather than a join — a join would
+			// multiply a user by their addresses and break both the page size
+			// and the count.
+			pattern := dbq.LikePattern(filter.Search)
+			primaryEmails := tx.From(ctx, r.db).WithContext(ctx).Model(&UserEmail{}).
+				Select("user_id").Where("is_primary = true AND email ILIKE ?", pattern)
+			q = q.Where("(name ILIKE ? OR id IN (?))", pattern, primaryEmails)
+		}
+		return q
+	}
+
+	var total int64
+	if err := matching().Count(&total).Error; err != nil {
+		return nil, 0, persistenceError(err)
+	}
+
 	var rows []User
-	err := tx.From(ctx, r.db).WithContext(ctx).
-		Order("created_at desc").Limit(limit).Offset(offset).Find(&rows).Error
+	// id breaks ties in created_at: without it two accounts created in the
+	// same instant can swap between page 1 and page 2, showing one twice and
+	// hiding the other.
+	err := matching().Order("created_at desc, id").Limit(filter.Limit).Offset(filter.Offset).Find(&rows).Error
 	if err != nil {
-		return nil, persistenceError(err)
+		return nil, 0, persistenceError(err)
 	}
 	ids := make([]uuid.UUID, len(rows))
 	for i := range rows {
@@ -91,7 +119,7 @@ func (r *Repository) FindAll(ctx context.Context, limit, offset int) ([]domain.U
 	if len(ids) > 0 {
 		if err := tx.From(ctx, r.db).WithContext(ctx).
 			Where("user_id IN ? AND is_primary = true", ids).Find(&emailRows).Error; err != nil {
-			return nil, persistenceError(err)
+			return nil, 0, persistenceError(err)
 		}
 	}
 	emails := make(map[uuid.UUID]*UserEmail, len(emailRows))
@@ -102,7 +130,7 @@ func (r *Repository) FindAll(ctx context.Context, limit, offset int) ([]domain.U
 	for i := range rows {
 		items[i] = *toDomainUserWithEmail(&rows[i], emails[rows[i].ID])
 	}
-	return items, nil
+	return items, total, nil
 }
 
 func (r *Repository) FindIdentity(ctx context.Context, userID uuid.UUID, provider domain.Provider) (*domain.Identity, error) {
@@ -254,23 +282,79 @@ func (r *Repository) LoginLockedUntil(ctx context.Context, key string) (time.Tim
 }
 
 // RecordLoginFailure uses one SQL statement so concurrent attempts cannot
-// both read and write the same backoff value.
-func (r *Repository) RecordLoginFailure(ctx context.Context, key string, freeAttempts int, maxLock time.Duration) error {
+// both read and write the same counter.
+//
+// attempt is an opaque fingerprint of the password that was submitted, or ""
+// for callers that have no password to fingerprint. Repeating the fingerprint
+// that is already on the row leaves the counter and the lock exactly where
+// they are: a browser replaying one saved, outdated password costs a single
+// attempt instead of all of them, while a guessing attack — which submits
+// something different every time — is untouched. "" never matches, so those
+// callers keep counting normally.
+//
+// The leading DELETE is the table's whole retention policy. A row for a handle
+// that never logs in successfully — a typo'd address, a sprayed list — is
+// never cleared by ClearLoginFailures, and it holds a fingerprint derived from
+// a real password, so it cannot simply sit there. A failed login is the only
+// moment this table is written, which makes it the only moment it can clean
+// itself, and no scheduler has to exist for that to work.
+//
+// The current key is excluded from the sweep on purpose: the DELETE and the
+// UPSERT run on the same snapshot and cannot see each other, so letting them
+// meet on one row makes the outcome depend on which one wins.
+{{#if fixedLockout}}//
+// A failure inside window continues the count, one after it starts over. With
+// window longer than the lock, sitting out a lock resets nothing: the next
+// wrong password trips it again.
+func (r *Repository) RecordLoginFailure(ctx context.Context, key, attempt string, maxAttempts int, lockFor, window time.Duration) error {
+	stale := window.Seconds()
+	err := tx.From(ctx, r.db).WithContext(ctx).Exec(`
+		WITH gc AS (
+			DELETE FROM user_svc.login_throttle
+			WHERE email_hash <> ? AND updated_at < now() - interval '1 day'
+		)
+		INSERT INTO user_svc.login_throttle AS t (email_hash, failures, last_attempt, locked_until, updated_at)
+		VALUES (?, 1, NULLIF(?, ''), NULL, now())
+		ON CONFLICT (email_hash) DO UPDATE SET
+			failures = CASE
+				WHEN t.last_attempt = ? THEN t.failures
+				WHEN t.updated_at < now() - make_interval(secs => ?) THEN 1
+				ELSE t.failures + 1
+			END,
+			locked_until = CASE
+				WHEN t.last_attempt = ? THEN t.locked_until
+				WHEN t.updated_at < now() - make_interval(secs => ?) THEN NULL
+				WHEN t.failures + 1 >= ? THEN now() + make_interval(secs => ?)
+				ELSE NULL
+			END,
+			last_attempt = NULLIF(?, ''),
+			updated_at = now()`,
+		key, key, attempt, attempt, stale, attempt, stale, maxAttempts, lockFor.Seconds(), attempt).Error
+	return persistenceError(err)
+}
+
+{{else}}func (r *Repository) RecordLoginFailure(ctx context.Context, key, attempt string, freeAttempts int, maxLock time.Duration) error {
 	err := tx.From(ctx, r.db).WithContext(ctx).Exec(`
-		INSERT INTO user_svc.login_throttle AS t (email_hash, failures, locked_until, updated_at)
-		VALUES (?, 1, NULL, now())
+		WITH gc AS (
+			DELETE FROM user_svc.login_throttle
+			WHERE email_hash <> ? AND updated_at < now() - interval '1 day'
+		)
+		INSERT INTO user_svc.login_throttle AS t (email_hash, failures, last_attempt, locked_until, updated_at)
+		VALUES (?, 1, NULLIF(?, ''), NULL, now())
 		ON CONFLICT (email_hash) DO UPDATE SET
-			failures = t.failures + 1,
+			failures = CASE WHEN t.last_attempt = ? THEN t.failures ELSE t.failures + 1 END,
 			locked_until = CASE
+				WHEN t.last_attempt = ? THEN t.locked_until
 				WHEN t.failures + 1 <= ? THEN NULL
 				ELSE now() + make_interval(secs => least(power(2, t.failures + 1 - ?), ?))
 			END,
+			last_attempt = NULLIF(?, ''),
 			updated_at = now()`,
-		key, freeAttempts, freeAttempts, maxLock.Seconds()).Error
+		key, key, attempt, attempt, attempt, freeAttempts, freeAttempts, maxLock.Seconds(), attempt).Error
 	return persistenceError(err)
 }
 
-func (r *Repository) ClearLoginFailures(ctx context.Context, key string) error {
+{{/if}}func (r *Repository) ClearLoginFailures(ctx context.Context, key string) error {
 	err := tx.From(ctx, r.db).WithContext(ctx).
 		Where("email_hash = ?", key).
 		Delete(&LoginThrottle{}).Error

package/templates/add/auth/internal/app/user/adapters/outbound/postgres/repository_test.go.hbs

@@ -2,6 +2,7 @@ package postgres
 
 import (
 	"context"
+	"fmt"
 	"errors"
 	"os"
 	"testing"
@@ -119,7 +120,91 @@ func TestRepository_CreateUserWithIdentity_DuplicateEmailIsDetectable(t *testing
 	}
 }
 
-// The backoff is computed by Postgres inside one UPSERT, so this is the only
+// throttle records one failed attempt, hiding this project's lockout
+// parameters from the tests that do not care about them. lockAt is the
+// attempt number that should set a lock.
+{{#if fixedLockout}}func throttle(ctx context.Context, repo *Repository, key, attempt string, lockAt int) error {
+	return repo.RecordLoginFailure(ctx, key, attempt, lockAt, 5*time.Minute, 15*time.Minute)
+}
+{{else}}func throttle(ctx context.Context, repo *Repository, key, attempt string, lockAt int) error {
+	return repo.RecordLoginFailure(ctx, key, attempt, lockAt-1, 15*time.Minute)
+}
+{{/if}}
+{{#if fixedLockout}}// The counter is computed by Postgres inside one UPSERT, so this is the only
+// place it can be checked — a fake can agree with itself about arithmetic the
+// database would reject.
+func TestRepository_LoginThrottle_LocksAtTheThresholdThenClears(t *testing.T) {
+	db := repositoryDBForTest(t)
+	repo := NewRepository(db)
+	ctx := context.Background()
+	key := "throttle-test-" + uuid.NewString()
+
+	// everything below the threshold leaves no lock behind
+	for i := 0; i < 2; i++ {
+		if err := throttle(ctx, repo, key, fmt.Sprintf("attempt-%d", i), 3); err != nil {
+			t.Fatalf("record failure %d: %v", i+1, err)
+		}
+		until, err := repo.LoginLockedUntil(ctx, key)
+		if err != nil {
+			t.Fatalf("read lock: %v", err)
+		}
+		if !until.IsZero() {
+			t.Fatalf("attempt %d is below the threshold but set a lock (%s)", i+1, until)
+		}
+	}
+
+	// the attempt that reaches it locks, for the configured span
+	if err := throttle(ctx, repo, key, "attempt-3", 3); err != nil {
+		t.Fatalf("record failure 3: %v", err)
+	}
+	until, err := repo.LoginLockedUntil(ctx, key)
+	if err != nil {
+		t.Fatalf("read lock: %v", err)
+	}
+	if remaining := time.Until(until); remaining < 4*time.Minute || remaining > 5*time.Minute {
+		t.Fatalf("expected a ~5 minute lock, got %s remaining", remaining)
+	}
+
+	// a successful login wipes the slate
+	if err := repo.ClearLoginFailures(ctx, key); err != nil {
+		t.Fatalf("clear: %v", err)
+	}
+	cleared, err := repo.LoginLockedUntil(ctx, key)
+	if err != nil || !cleared.IsZero() {
+		t.Fatalf("expected no lock after clearing, got %s (err %v)", cleared, err)
+	}
+}
+
+// The third knob: without it the count would only ever be cleared by a
+// successful login, so a typo from last week would still count towards today's
+// lock. now() is frozen inside this test's transaction, so the wait is
+// simulated by backdating the row rather than by sleeping.
+func TestRepository_LoginThrottle_CountExpiresAfterAQuietWindow(t *testing.T) {
+	db := repositoryDBForTest(t)
+	repo := NewRepository(db)
+	ctx := context.Background()
+	key := "throttle-window-" + uuid.NewString()
+
+	if err := throttle(ctx, repo, key, "first-attempt", 2); err != nil {
+		t.Fatalf("record first failure: %v", err)
+	}
+	if err := db.Exec(`UPDATE user_svc.login_throttle SET updated_at = now() - interval '16 minutes' WHERE email_hash = ?`, key).Error; err != nil {
+		t.Fatalf("backdate the row: %v", err)
+	}
+	if err := throttle(ctx, repo, key, "second-attempt", 2); err != nil {
+		t.Fatalf("record second failure: %v", err)
+	}
+
+	until, err := repo.LoginLockedUntil(ctx, key)
+	if err != nil {
+		t.Fatalf("read lock: %v", err)
+	}
+	if !until.IsZero() {
+		t.Fatalf("the failure after a quiet window counted as the second, not the first: locked until %s", until)
+	}
+}
+
+{{else}}// The backoff is computed by Postgres inside one UPSERT, so this is the only
 // place it can be checked — a fake can agree with itself about arithmetic the
 // database would reject.
 func TestRepository_LoginThrottle_BacksOffThenClears(t *testing.T) {
@@ -130,7 +215,7 @@ func TestRepository_LoginThrottle_BacksOffThenClears(t *testing.T) {
 
 	// the free attempts leave no lock behind
 	for i := 0; i < 3; i++ {
-		if err := repo.RecordLoginFailure(ctx, key, 3, 15*time.Minute); err != nil {
+		if err := repo.RecordLoginFailure(ctx, key, fmt.Sprintf("attempt-%d", i), 3, 15*time.Minute); err != nil {
 			t.Fatalf("record failure %d: %v", i+1, err)
 		}
 		until, err := repo.LoginLockedUntil(ctx, key)
@@ -143,14 +228,14 @@ func TestRepository_LoginThrottle_BacksOffThenClears(t *testing.T) {
 	}
 
 	// the next one locks, and the one after that locks for longer
-	if err := repo.RecordLoginFailure(ctx, key, 3, 15*time.Minute); err != nil {
+	if err := repo.RecordLoginFailure(ctx, key, "attempt-4", 3, 15*time.Minute); err != nil {
 		t.Fatalf("record failure 4: %v", err)
 	}
 	first, err := repo.LoginLockedUntil(ctx, key)
 	if err != nil || first.IsZero() {
 		t.Fatalf("expected a lock after exceeding the free allowance, got %s (err %v)", first, err)
 	}
-	if err := repo.RecordLoginFailure(ctx, key, 3, 15*time.Minute); err != nil {
+	if err := repo.RecordLoginFailure(ctx, key, "attempt-5", 3, 15*time.Minute); err != nil {
 		t.Fatalf("record failure 5: %v", err)
 	}
 	second, err := repo.LoginLockedUntil(ctx, key)
@@ -180,7 +265,7 @@ func TestRepository_LoginThrottle_RespectsTheCeiling(t *testing.T) {
 	key := "throttle-cap-" + uuid.NewString()
 
 	for i := 0; i < 12; i++ {
-		if err := repo.RecordLoginFailure(ctx, key, 0, 5*time.Second); err != nil {
+		if err := repo.RecordLoginFailure(ctx, key, fmt.Sprintf("attempt-%d", i), 0, 5*time.Second); err != nil {
 			t.Fatalf("record failure %d: %v", i+1, err)
 		}
 	}
@@ -192,3 +277,82 @@ func TestRepository_LoginThrottle_RespectsTheCeiling(t *testing.T) {
 		t.Fatalf("lock ran past its 5s ceiling: %s remaining", remaining)
 	}
 }
+
+{{/if}}// The repeat rule lives in SQL, so only the database can prove it. This is the
+// browser-with-a-saved-password case: one wrong password sent over and over
+// costs one attempt, no matter how many times it arrives.
+func TestRepository_LoginThrottle_CountsARepeatedAttemptOnce(t *testing.T) {
+	db := repositoryDBForTest(t)
+	repo := NewRepository(db)
+	ctx := context.Background()
+	key := "throttle-repeat-" + uuid.NewString()
+
+	for i := 0; i < 8; i++ {
+		if err := throttle(ctx, repo, key, "one-stale-password", 3); err != nil {
+			t.Fatalf("record failure %d: %v", i+1, err)
+		}
+	}
+	until, err := repo.LoginLockedUntil(ctx, key)
+	if err != nil {
+		t.Fatalf("read lock: %v", err)
+	}
+	if !until.IsZero() {
+		t.Fatalf("the same wrong password locked the account (%s); it should count once", until)
+	}
+
+	// an empty fingerprint is "no password to compare" — those callers, like
+	// the password reset counter, must keep counting every attempt.
+	blank := "throttle-blank-" + uuid.NewString()
+	for i := 0; i < 8; i++ {
+		if err := throttle(ctx, repo, blank, "", 3); err != nil {
+			t.Fatalf("record blank failure %d: %v", i+1, err)
+		}
+	}
+	locked, err := repo.LoginLockedUntil(ctx, blank)
+	if err != nil {
+		t.Fatalf("read lock: %v", err)
+	}
+	if locked.IsZero() {
+		t.Fatal("attempts without a fingerprint never locked; they must not be treated as repeats of each other")
+	}
+}
+
+// Retention with no scheduler: the sweep rides along with the next failure,
+// whoever it belongs to. Without it a row for a handle that never logs in
+// successfully — a mistyped address is enough — keeps a fingerprint of a real
+// password for good.
+func TestRepository_LoginThrottle_SweepsRowsNothingTouchesAnyMore(t *testing.T) {
+	db := repositoryDBForTest(t)
+	repo := NewRepository(db)
+	ctx := context.Background()
+	stale := "throttle-stale-" + uuid.NewString()
+	fresh := "throttle-fresh-" + uuid.NewString()
+
+	for _, key := range []string{stale, fresh} {
+		if err := throttle(ctx, repo, key, "some-password", 3); err != nil {
+			t.Fatalf("seed %s: %v", key, err)
+		}
+	}
+	if err := db.Exec(`UPDATE user_svc.login_throttle SET updated_at = now() - interval '2 days' WHERE email_hash = ?`, stale).Error; err != nil {
+		t.Fatalf("age the row: %v", err)
+	}
+
+	// somebody else's failed login, later that week
+	if err := throttle(ctx, repo, "throttle-other-"+uuid.NewString(), "another-password", 3); err != nil {
+		t.Fatalf("record unrelated failure: %v", err)
+	}
+
+	count := func(key string) int64 {
+		var n int64
+		if err := db.Raw(`SELECT count(*) FROM user_svc.login_throttle WHERE email_hash = ?`, key).Scan(&n).Error; err != nil {
+			t.Fatalf("count %s: %v", key, err)
+		}
+		return n
+	}
+	if count(stale) != 0 {
+		t.Fatal("a row nothing has touched for two days survived the sweep")
+	}
+	if count(fresh) != 1 {
+		t.Fatal("the sweep took a row that is still counting")
+	}
+}

package/templates/add/auth/internal/app/user/application/local_auth.go.hbs

@@ -2,6 +2,9 @@ package application
 
 import (
 	"context"
+	"crypto/hmac"
+	"crypto/sha256"
+	"encoding/hex"
 	"errors"
 	"fmt"
 	"log/slog"
@@ -11,13 +14,35 @@ import (
 	"{{goModule}}/internal/shared/id"
 )
 
-// Failed-attempt policy. These values are security posture rather than
+{{#if fixedLockout}}// Failed-attempt policy, the shape enterprise directories use: a threshold, a
+// lock duration, and a window after which the count expires. These values are
+// security posture rather than per-environment tuning knobs.
+//
+// The window is longer than the lock on purpose. Sitting out a lock is not the
+// same as walking away: the count survives it, so the eleventh wrong password
+// locks again instead of buying another ten tries. Only fifteen quiet minutes
+// clear the slate, which also means yesterday's typos never shorten today's
+// allowance.
+const (
+	loginMaxAttempts = 10
+	loginLockFor     = 5 * time.Minute
+	loginCountWindow = 15 * time.Minute
+)
+{{else}}// Failed-attempt policy. These values are security posture rather than
 // per-environment tuning knobs. The first few failures cost nothing, then the
 // wait doubles up to a bounded maximum.
 const (
 	loginFreeAttempts = 3
 	loginMaxLock      = 15 * time.Minute
 )
+{{/if}}
+// recordFailure is where the policy above meets the counter. Callers hand it
+// one failed attempt and never repeat the parameter list.
+func (s *Service) recordFailure(ctx context.Context, key, attempt string) error {
+{{#if fixedLockout}}	return s.repo.RecordLoginFailure(ctx, key, attempt, loginMaxAttempts, loginLockFor, loginCountWindow)
+{{else}}	return s.repo.RecordLoginFailure(ctx, key, attempt, loginFreeAttempts, loginMaxLock)
+{{/if}}
+}
 
 // throttleKey namespaces the counter by purpose, so a locked login never
 // blocks the password reset that would fix it. The address is hashed because
@@ -26,6 +51,22 @@ func throttleKey(purpose, email string) string {
 	return hashToken(purpose + ":" + normalizeEmail(email))
 }
 
+// attemptFingerprint identifies the password that was submitted so the counter
+// can ignore a repeat of one it has already punished. A saved password that
+// went stale gets replayed by the browser on every visit and would otherwise
+// lock the account out on its own, while an attacker gains nothing: guessing
+// means sending something new each time.
+//
+// It is an HMAC under the signing secret rather than a bare hash. The value
+// is derived from a real password — often the user's password somewhere else,
+// or one character away from the right one — so a leak of this table alone
+// must not be crackable offline.
+func (s *Service) attemptFingerprint(password string) string {
+	mac := hmac.New(sha256.New, []byte(s.config.JWTSecret))
+	mac.Write([]byte(password))
+	return hex.EncodeToString(mac.Sum(nil))
+}
+
 // throttled treats a counter read failure as not-throttled: this is a brake,
 // and it should not be able to lock everybody out on its own.
 func (s *Service) throttled(ctx context.Context, key string) bool {
@@ -73,8 +114,9 @@ func (s *Service) Login(ctx context.Context, in LoginInput) (*AuthResult, error)
 
 	// Every failure records the same key and returns the same error whether or
 	// not the account exists, preventing account enumeration through the counter.
+	attempt := s.attemptFingerprint(in.Password)
 	fail := func() (*AuthResult, error) {
-		if err := s.repo.RecordLoginFailure(ctx, key, loginFreeAttempts, loginMaxLock); err != nil {
+		if err := s.recordFailure(ctx, key, attempt); err != nil {
 			slog.Error("record login failure", "error", err)
 		}
 		return nil, errInvalidCredentials()

package/templates/add/auth/internal/app/user/application/recovery_service.go.hbs

@@ -19,7 +19,8 @@ func (s *Service) ForgotPassword(ctx context.Context, email string) error {
 	if s.throttled(ctx, key) {
 		return nil
 	}
-	if err := s.repo.RecordLoginFailure(ctx, key, loginFreeAttempts, loginMaxLock); err != nil {
+	// no password to fingerprint here, so every request counts
+	if err := s.recordFailure(ctx, key, ""); err != nil {
 		slog.Error("record password reset attempt", "error", err)
 	}
 

package/templates/add/auth/internal/app/user/application/service.go.hbs

@@ -154,7 +154,7 @@ type ServicePort interface {
 	ConfirmMFA(context.Context, uuid.UUID, string) ([]string, error)
 	DisableMFA(context.Context, uuid.UUID, string) error
 	Get(context.Context, uuid.UUID) (*domain.User, error)
-	List(context.Context, int, int) ([]domain.User, error)
+	List(context.Context, ports.ListFilter) ([]domain.User, int64, error)
 	SetRole(context.Context, uuid.UUID, string) (*domain.User, error)
 }
 

package/templates/add/auth/internal/app/user/application/service_test.go.hbs

@@ -10,6 +10,7 @@ import (
 	"time"
 
 	"{{goModule}}/internal/app/user/domain"
+	"{{goModule}}/internal/app/user/ports"
 
 	"github.com/google/uuid"
 )
@@ -338,6 +339,7 @@ type fakeRepo struct {
 	updateIdentityErr error
 	updateUserErr     error
 	failures          map[string]int
+	lastAttempt       map[string]string
 	lockedUntil       map[string]time.Time
 	// go-scaffold:repository-stub-fields
 }
@@ -350,23 +352,44 @@ func (f *fakeRepo) LoginLockedUntil(_ context.Context, key string) (time.Time, e
 	return f.lockedUntil[key], nil
 }
 
-func (f *fakeRepo) RecordLoginFailure(_ context.Context, key string, freeAttempts int, maxLock time.Duration) error {
-	if f.lockedUntil == nil {
+// lockoutAfter is how many distinct wrong passwords it takes to be locked out
+// under this project's policy, so the tests below read the same either way.
+{{#if fixedLockout}}const lockoutAfter = loginMaxAttempts
+{{else}}const lockoutAfter = loginFreeAttempts + 1
+{{/if}}
+{{#if fixedLockout}}func (f *fakeRepo) RecordLoginFailure(_ context.Context, key, attempt string, maxAttempts int, lockFor, _ time.Duration) error {
+{{else}}func (f *fakeRepo) RecordLoginFailure(_ context.Context, key, attempt string, freeAttempts int, maxLock time.Duration) error {
+{{/if}}	if f.lockedUntil == nil {
 		f.lockedUntil = map[string]time.Time{}
 	}
+	if f.lastAttempt == nil {
+		f.lastAttempt = map[string]string{}
+	}
+	// same rule as the SQL: a repeat of the fingerprint already on the row
+	// changes nothing, and "" is never a repeat
+	if attempt != "" && f.lastAttempt[key] == attempt {
+		return nil
+	}
+	f.lastAttempt[key] = attempt
 	f.failures[key]++
-	if f.failures[key] > freeAttempts {
+{{#if fixedLockout}}	// the expiry window is left to the repository test: nothing here waits
+	// fifteen minutes, and Postgres is what computes it
+	if f.failures[key] >= maxAttempts {
+		f.lockedUntil[key] = time.Now().Add(lockFor)
+	}
+{{else}}	if f.failures[key] > freeAttempts {
 		lock := time.Duration(1<<uint(f.failures[key]-freeAttempts-1)) * time.Second
 		if lock > maxLock {
 			lock = maxLock
 		}
 		f.lockedUntil[key] = time.Now().Add(lock)
 	}
-	return nil
+{{/if}}	return nil
 }
 
 func (f *fakeRepo) ClearLoginFailures(_ context.Context, key string) error {
 	delete(f.failures, key)
+	delete(f.lastAttempt, key)
 	delete(f.lockedUntil, key)
 	return nil
 }
@@ -387,7 +410,9 @@ func (f *fakeRepo) UpdateUser(_ context.Context, u *domain.User) error {
 	f.user = u
 	return nil
 }
-func (f *fakeRepo) FindAll(context.Context, int, int) ([]domain.User, error) { return nil, nil }
+func (f *fakeRepo) FindAll(context.Context, ports.ListFilter) ([]domain.User, int64, error) {
+	return nil, 0, nil
+}
 
 func (f *fakeRepo) FindIdentity(_ context.Context, userID uuid.UUID, provider domain.Provider) (*domain.Identity, error) {
 	for i := range f.identities {
@@ -946,18 +971,21 @@ func TestService_VerifyEmail_ConcurrentPresentationHasOneWinner(t *testing.T) {
 }
 
 // The control that actually stops credential stuffing: the counter follows the
-// account, so spreading attempts across a proxy pool doesn't help.
+// account, so spreading attempts across a proxy pool doesn't help. Every guess
+// here is a different password, which is what guessing looks like.
 func TestService_Login_LocksTheAccountAfterRepeatedFailures(t *testing.T) {
 	repo := &fakeRepo{
 		user:     &domain.User{ID: uuid.New(), Email: "a@example.com"},
 		failures: map[string]int{},
 	}
 	svc := newTestService(repo, newFakeTokenStore())
-	in := LoginInput{Email: "a@example.com", Password: "wrong"}
+	guess := func(n int) LoginInput {
+		return LoginInput{Email: "a@example.com", Password: fmt.Sprintf("wrong-%d", n)}
+	}
 
-	// the free attempts answer "wrong password", not "locked"
-	for i := 0; i < loginFreeAttempts; i++ {
-		if _, err := svc.Login(context.Background(), in); err == nil {
+	// everything below the limit answers "wrong password", not "locked"
+	for i := 0; i < lockoutAfter-1; i++ {
+		if _, err := svc.Login(context.Background(), guess(i)); err == nil {
 			t.Fatalf("attempt %d: expected a failure", i+1)
 		} else if code(err) != "AUTH_INVALID_CREDENTIALS" {
 			t.Fatalf("attempt %d: expected AUTH_INVALID_CREDENTIALS, got %s", i+1, code(err))
@@ -965,15 +993,46 @@ func TestService_Login_LocksTheAccountAfterRepeatedFailures(t *testing.T) {
 	}
 
 	// the next one trips the lock...
-	if _, err := svc.Login(context.Background(), in); code(err) != "AUTH_INVALID_CREDENTIALS" {
+	if _, err := svc.Login(context.Background(), guess(lockoutAfter)); code(err) != "AUTH_INVALID_CREDENTIALS" {
 		t.Fatalf("the attempt that trips the lock still answers as a bad password, got %s", code(err))
 	}
 	// ...and everything after it is refused before any password is checked
-	if _, err := svc.Login(context.Background(), in); code(err) != "AUTH_TOO_MANY_ATTEMPTS" {
+	if _, err := svc.Login(context.Background(), guess(lockoutAfter+1)); code(err) != "AUTH_TOO_MANY_ATTEMPTS" {
 		t.Fatalf("expected AUTH_TOO_MANY_ATTEMPTS once locked, got %s", code(err))
 	}
 }
 
+// The other half of that rule: one wrong password replayed forever is a stale
+// saved credential, not an attack, and must never lock the account. Without
+// this the browser locks the user out of their own account on a schedule.
+func TestService_Login_CountsOneWrongPasswordOnce(t *testing.T) {
+	repo := &fakeRepo{
+		user:     &domain.User{ID: uuid.New(), Email: "a@example.com"},
+		failures: map[string]int{},
+	}
+	svc := newTestService(repo, newFakeTokenStore())
+	saved := LoginInput{Email: "a@example.com", Password: "last-years-password"}
+
+	for i := 0; i < lockoutAfter*4; i++ {
+		if _, err := svc.Login(context.Background(), saved); code(err) != "AUTH_INVALID_CREDENTIALS" {
+			t.Fatalf("replay %d: one stale password should never lock, got %s", i+1, code(err))
+		}
+	}
+
+	// passwords it has not seen are new material: enough of those still lock,
+	// and the lock then covers the replayed one too
+	for i := 0; i < lockoutAfter; i++ {
+		if _, err := svc.Login(context.Background(), LoginInput{
+			Email: "a@example.com", Password: fmt.Sprintf("guess-%d", i),
+		}); err == nil {
+			t.Fatalf("guess %d: expected a failure", i+1)
+		}
+	}
+	if _, err := svc.Login(context.Background(), saved); code(err) != "AUTH_TOO_MANY_ATTEMPTS" {
+		t.Fatalf("expected the lock once real guesses arrived, got %s", code(err))
+	}
+}
+
 // A locked login must not lock the reset that fixes it — the person who forgot
 // their password is exactly the person who trips the login counter.
 func TestService_ForgotPassword_HasItsOwnCounter(t *testing.T) {

package/templates/add/auth/internal/app/user/application/user_query.go.hbs

@@ -6,6 +6,7 @@ import (
 	"fmt"
 
 	"{{goModule}}/internal/app/user/domain"
+	"{{goModule}}/internal/app/user/ports"
 	"{{goModule}}/internal/shared/id"
 
 	"github.com/google/uuid"
@@ -32,12 +33,12 @@ func (s *Service) Get(ctx context.Context, userID uuid.UUID) (*domain.User, erro
 
 // List is kept for the optional RBAC admin routes. It is not part of the
 // public self-service auth surface until that feature is installed.
-func (s *Service) List(ctx context.Context, limit, offset int) ([]domain.User, error) {
-	items, err := s.repo.FindAll(ctx, limit, offset)
+func (s *Service) List(ctx context.Context, filter ports.ListFilter) ([]domain.User, int64, error) {
+	items, total, err := s.repo.FindAll(ctx, filter)
 	if err != nil {
-		return nil, fmt.Errorf("list users: %w", err)
+		return nil, 0, fmt.Errorf("list users: %w", err)
 	}
-	return items, nil
+	return items, total, nil
 }
 
 // EnsureUser is idempotent and used only by cmd/seed. It never resets an

package/templates/add/auth/internal/app/user/domain/errors.go.hbs

@@ -3,6 +3,10 @@ package domain
 import "errors"
 
 var (
+	// What every endpoint `generate method` adds returns until an engineer
+	// writes its body. The inbound adapter maps it to 501, so a scaffolded
+	// route answers "not built yet" rather than reporting a server fault.
+	ErrNotImplemented    = errors.New("user operation is not implemented")
 	ErrNotFound          = errors.New("user not found")
 	ErrConflict          = errors.New("user conflict")
 	ErrInvalidCredential = errors.New("invalid credentials")