@nakedev/go-scaffold 0.1.3 → 0.3.0

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

@@ -0,0 +1,192 @@
+package user
+
+import (
+	"time"
+	"context"
+	"errors"
+	"os"
+	"testing"
+
+	"{{goModule}}/internal/app/user/model"
+	"{{goModule}}/internal/shared/dberr"
+
+	"github.com/google/uuid"
+	"gorm.io/driver/postgres"
+	"gorm.io/gorm"
+)
+
+// repositoryDBForTest expects the test database schema to come from the same
+// versioned SQL migrations used in production. Unit tests stay database-free;
+// CI sets REQUIRE_TEST_DB=true so an unavailable/unmigrated database fails
+// instead of becoming a false-green skip. Same pattern as every generated
+// module's repository_test.go.
+func repositoryDBForTest(t *testing.T) *gorm.DB {
+	t.Helper()
+	dsn := os.Getenv("TEST_DB_DSN")
+	if dsn == "" {
+		if os.Getenv("REQUIRE_TEST_DB") == "true" {
+			t.Fatal("TEST_DB_DSN is required when REQUIRE_TEST_DB=true")
+		}
+		t.Skip("repository integration test skipped: set TEST_DB_DSN to a migrated PostgreSQL database")
+	}
+
+	db, err := gorm.Open(postgres.Open(dsn), &gorm.Config{TranslateError: true})
+	if err != nil {
+		if os.Getenv("REQUIRE_TEST_DB") == "true" {
+			t.Fatalf("open required test database: %v", err)
+		}
+		t.Skipf("repository integration test skipped: %v", err)
+	}
+
+	sqlDB, err := db.DB()
+	if err != nil {
+		t.Fatalf("get SQL database handle: %v", err)
+	}
+	if err := sqlDB.Ping(); err != nil {
+		if os.Getenv("REQUIRE_TEST_DB") == "true" {
+			t.Fatalf("ping required test database: %v", err)
+		}
+		t.Skipf("repository integration test skipped: %v", err)
+	}
+
+	tx := db.Begin()
+	if tx.Error != nil {
+		t.Fatalf("begin test transaction: %v", tx.Error)
+	}
+	t.Cleanup(func() {
+		if err := tx.Rollback().Error; err != nil {
+			t.Errorf("rollback test transaction: %v", err)
+		}
+	})
+	return tx
+}
+
+// CreateUserWithIdentity's whole reason to be a transaction: a user that
+// exists with no way to log in is unreachable. If the identity insert fails,
+// the user it was meant to arrive with must vanish too — a function-backed
+// stub can't prove this, since it never runs a real insert against a real
+// constraint. This forces exactly that: the user insert succeeds (it's a
+// brand new row), but the identity insert collides with an existing Google
+// identity's provider_uid.
+func TestRepository_CreateUserWithIdentity_RollsBackBothOnIdentityConflict(t *testing.T) {
+	repo := NewRepository(repositoryDBForTest(t))
+	ctx := context.Background()
+
+	providerUID := "conflicting-provider-uid"
+	existing := &model.User{ID: uuid.New(), Email: "first@example.com"}
+	if err := repo.CreateUserWithIdentity(ctx, existing, &model.Identity{
+		ID: uuid.New(), Provider: model.ProviderGoogle, ProviderUID: &providerUID,
+	}); err != nil {
+		t.Fatalf("seed existing user+identity: %v", err)
+	}
+
+	blocked := &model.User{ID: uuid.New(), Email: "second@example.com"}
+	err := repo.CreateUserWithIdentity(ctx, blocked, &model.Identity{
+		ID: uuid.New(), Provider: model.ProviderGoogle, ProviderUID: &providerUID,
+	})
+	if !dberr.IsDuplicate(err) {
+		t.Fatalf("want a duplicate-key error from the conflicting provider_uid, got %v", err)
+	}
+
+	if _, findErr := repo.FindByID(ctx, blocked.ID); !errors.Is(findErr, gorm.ErrRecordNotFound) {
+		t.Fatalf("the new user must not survive a transaction whose identity insert failed, got %v", findErr)
+	}
+}
+
+// The unique index on email is what actually stops two accounts sharing a
+// login — Register's "email already registered" response depends on the
+// database enforcing it, not on an application-level check (which would
+// race). Confirms the constraint is really there and that dberr recognizes
+// the violation shape Postgres returns.
+func TestRepository_CreateUserWithIdentity_DuplicateEmailIsDetectable(t *testing.T) {
+	repo := NewRepository(repositoryDBForTest(t))
+	ctx := context.Background()
+
+	email := "dup@example.com"
+	if err := repo.CreateUserWithIdentity(ctx, &model.User{ID: uuid.New(), Email: email}, &model.Identity{
+		ID: uuid.New(), Provider: model.ProviderLocal,
+	}); err != nil {
+		t.Fatalf("seed first user: %v", err)
+	}
+
+	err := repo.CreateUserWithIdentity(ctx, &model.User{ID: uuid.New(), Email: email}, &model.Identity{
+		ID: uuid.New(), Provider: model.ProviderLocal,
+	})
+	if !dberr.IsDuplicate(err) {
+		t.Fatalf("want a duplicate-key error for the reused email, got %v", err)
+	}
+}
+
+// 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) {
+	db := repositoryDBForTest(t)
+	repo := NewRepository(db)
+	ctx := context.Background()
+	key := "throttle-test-" + uuid.NewString()
+
+	// 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 {
+			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 within the free allowance but set a lock (%s)", i+1, until)
+		}
+	}
+
+	// the next one locks, and the one after that locks for longer
+	if err := repo.RecordLoginFailure(ctx, key, 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 {
+		t.Fatalf("record failure 5: %v", err)
+	}
+	second, err := repo.LoginLockedUntil(ctx, key)
+	if err != nil {
+		t.Fatalf("read lock: %v", err)
+	}
+	if !second.After(first) {
+		t.Fatalf("the backoff did not grow: %s then %s", first, second)
+	}
+
+	// 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)
+	}
+}
+
+// maxLock is a ceiling, not a suggestion: without it the doubling reaches
+// "locked for a week" in about twenty attempts.
+func TestRepository_LoginThrottle_RespectsTheCeiling(t *testing.T) {
+	db := repositoryDBForTest(t)
+	repo := NewRepository(db)
+	ctx := context.Background()
+	key := "throttle-cap-" + uuid.NewString()
+
+	for i := 0; i < 12; i++ {
+		if err := repo.RecordLoginFailure(ctx, key, 0, 5*time.Second); 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 remaining := time.Until(until); remaining > 30*time.Second {
+		t.Fatalf("lock ran past its 5s ceiling: %s remaining", remaining)
+	}
+}

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

@@ -34,14 +34,18 @@ type repository interface {
 	CreateUserWithIdentity(ctx context.Context, u *model.User, i *model.Identity) error
 	CreateIdentity(ctx context.Context, i *model.Identity) error
 	UpdateIdentity(ctx context.Context, i *model.Identity) error
+	LoginLockedUntil(ctx context.Context, key string) (time.Time, error)
+	RecordLoginFailure(ctx context.Context, key string, freeAttempts int, maxLock time.Duration) error
+	ClearLoginFailures(ctx context.Context, key string) error
 	// go-scaffold:user-repository-interface
 }
 
 // mailer = what the service needs to send an email — satisfied by
 // platform/mail's AsyncClient (enqueues onto cmd/worker instead of blocking
-// the request on SMTP).
+// the request on SMTP). Takes ctx so the enqueue can join the caller's
+// transaction where the queue backend supports it.
 type mailer interface {
-	Send(to, subject, body string) error
+	Send(ctx context.Context, to, subject, body string) error
 }
 
 // go-scaffold:user-interfaces
@@ -90,6 +94,52 @@ func NewService(
 	}
 }
 
+// normalizeEmail is applied at every boundary an address enters the service
+// through. The column is a plain case-sensitive UNIQUE, so without this
+// "Foo@x.com" and "foo@x.com" are two accounts that never collide — and a
+// Google login (Google always reports lowercase) fails to find the local
+// account it should have linked to, silently creating a second user for the
+// same person.
+func normalizeEmail(email string) string {
+	return strings.ToLower(strings.TrimSpace(email))
+}
+
+// Failed-attempt policy. Constants rather than config: these are a security
+// posture, not something to tune per environment, and every knob added here is
+// a knob someone can quietly widen until the control stops working. Change the
+// numbers if your threat model differs.
+//
+// The first loginFreeAttempts failures cost nothing — a typo shouldn't lock
+// anyone out. After that each failure doubles the wait (1s, 2s, 4s, ...) up to
+// loginMaxLock, which is the shape OWASP's Authentication Cheat Sheet asks for.
+const (
+	loginFreeAttempts = 3
+	loginMaxLock      = 15 * time.Minute
+)
+
+// throttleKey namespaces the counter by what is being attempted, so a locked
+// login never blocks the password-reset that would fix it — someone who forgot
+// their password is exactly the person who trips the login counter.
+//
+// Hashed, because the counter must exist for addresses that have no account
+// (otherwise "was I throttled" answers "does this account exist"), and a table
+// of plain addresses that anyone has ever typed is a user list.
+func throttleKey(purpose, email string) string {
+	return hashToken(purpose + ":" + normalizeEmail(email))
+}
+
+// throttled reports whether this key is inside its lockout window. A failure
+// to read the counter is treated 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 {
+	until, err := s.repo.LoginLockedUntil(ctx, key)
+	if err != nil {
+		slog.Error("read login throttle", "error", err)
+		return false
+	}
+	return !until.IsZero() && time.Now().Before(until)
+}
+
 func (s *Service) Register(ctx context.Context, in registerInput) (*authResponse, error) {
 	hash, err := bcrypt.GenerateFromPassword([]byte(in.Password), bcrypt.DefaultCost)
 	if err != nil {
@@ -97,7 +147,7 @@ func (s *Service) Register(ctx context.Context, in registerInput) (*authResponse
 	}
 	hashStr := string(hash)
 
-	u := &model.User{ID: id.New(), Email: in.Email, Name: in.Name}
+	u := &model.User{ID: id.New(), Email: normalizeEmail(in.Email), Name: in.Name}
 	i := &model.Identity{ID: id.New(), Provider: model.ProviderLocal, PasswordHash: &hashStr}
 	if err := s.repo.CreateUserWithIdentity(ctx, u, i); err != nil {
 		if dberr.IsDuplicate(err) {
@@ -112,16 +162,35 @@ func (s *Service) Register(ctx context.Context, in registerInput) (*authResponse
 }
 
 func (s *Service) Login(ctx context.Context, in loginInput) (*authResponse, error) {
-	u, err := s.repo.FindByEmail(ctx, in.Email)
-	if err != nil {
+	key := throttleKey("login", in.Email)
+	if s.throttled(ctx, key) {
+		return nil, errTooManyAttempts()
+	}
+
+	// Every failure below is recorded against the same key whether or not the
+	// account exists, and answers with the same error — so the counter cannot
+	// be used to enumerate accounts either.
+	fail := func() (*authResponse, error) {
+		if err := s.repo.RecordLoginFailure(ctx, key, loginFreeAttempts, loginMaxLock); err != nil {
+			slog.Error("record login failure", "error", err)
+		}
 		return nil, errInvalidCredentials()
 	}
+
+	u, err := s.repo.FindByEmail(ctx, normalizeEmail(in.Email))
+	if err != nil {
+		return fail()
+	}
 	ident, err := s.repo.FindIdentity(ctx, u.ID, model.ProviderLocal)
 	if err != nil || ident.PasswordHash == nil {
-		return nil, errInvalidCredentials()
+		return fail()
 	}
 	if err := bcrypt.CompareHashAndPassword([]byte(*ident.PasswordHash), []byte(in.Password)); err != nil {
-		return nil, errInvalidCredentials()
+		return fail()
+	}
+
+	if err := s.repo.ClearLoginFailures(ctx, key); err != nil {
+		slog.Error("clear login failures", "error", err)
 	}
 	return s.issueTokens(ctx, u)
 }
@@ -206,7 +275,19 @@ func (s *Service) List(ctx context.Context, limit, offset int) ([]model.User, er
 // enumerate registered accounts. Only if the email resolves to a local
 // (password-based) identity does it actually issue+email a reset token.
 func (s *Service) ForgotPassword(ctx context.Context, email string) error {
-	u, err := s.repo.FindByEmail(ctx, email)
+	// Its own counter, so hammering this endpoint cannot lock anyone out of
+	// logging in, and a locked-out login cannot block the reset that fixes it.
+	// Every request counts here, not just failures: what this throttles is
+	// using someone else's address as a mail-bomb target.
+	key := throttleKey("pwreset", email)
+	if s.throttled(ctx, key) {
+		return nil // same answer as always — silence is the whole design here
+	}
+	if err := s.repo.RecordLoginFailure(ctx, key, loginFreeAttempts, loginMaxLock); err != nil {
+		slog.Error("record password reset attempt", "error", err)
+	}
+
+	u, err := s.repo.FindByEmail(ctx, normalizeEmail(email))
 	if err != nil {
 		return nil
 	}
@@ -224,7 +305,7 @@ func (s *Service) ForgotPassword(ctx context.Context, email string) error {
 	}
 
 	link := s.resetURL + "?token=" + raw
-	if err := s.mailer.Send(u.Email, "Reset your password", "Reset your password: "+link); err != nil {
+	if err := s.mailer.Send(ctx, u.Email, "Reset your password", "Reset your password: "+link); err != nil {
 		// token's already stored — a mail failure shouldn't fail the request,
 		// just get logged so it's visible operationally.
 		slog.Error("send password reset email", "error", err)
@@ -278,7 +359,7 @@ func (s *Service) sendVerificationEmail(ctx context.Context, u *model.User) {
 		return
 	}
 	link := s.verifyURL + "?token=" + raw
-	if err := s.mailer.Send(u.Email, "Verify your email", "Verify your email: "+link); err != nil {
+	if err := s.mailer.Send(ctx, u.Email, "Verify your email", "Verify your email: "+link); err != nil {
 		slog.Error("send email verification email", "error", err)
 	}
 }
@@ -318,14 +399,16 @@ func (s *Service) VerifyEmail(ctx context.Context, rawToken string) error {
 	return s.repo.UpdateUser(ctx, u)
 }
 
-// GoogleLoginURL signs a short-lived CSRF state token and builds the
-// redirect URL — stateless, no server-side row for the state (see jwt.go).
-func (s *Service) GoogleLoginURL() (string, error) {
-	state, err := s.issueOAuthState()
+// GoogleLoginURL signs a short-lived CSRF state token and builds the redirect
+// URL. The second return value is the nonce the caller must set as a cookie:
+// the callback checks it against the one inside the state (see jwt.go), which
+// is what binds the flow to this one browser.
+func (s *Service) GoogleLoginURL() (string, string, error) {
+	state, nonce, err := s.issueOAuthState()
 	if err != nil {
-		return "", apperror.NewInternal()
+		return "", "", apperror.NewInternal()
 	}
-	return s.googleOAuth.AuthCodeURL(state), nil
+	return s.googleOAuth.AuthCodeURL(state), nonce, nil
 }
 
 type googleUserInfo struct {
@@ -336,8 +419,8 @@ type googleUserInfo struct {
 	Picture       string `json:"picture"`
 }
 
-func (s *Service) GoogleCallback(ctx context.Context, code, state string) (*authResponse, error) {
-	if err := s.verifyOAuthState(state); err != nil {
+func (s *Service) GoogleCallback(ctx context.Context, code, state, nonce string) (*authResponse, error) {
+	if err := s.verifyOAuthState(state, nonce); err != nil {
 		return nil, err
 	}
 	tok, err := s.googleOAuth.Exchange(ctx, code)
@@ -376,8 +459,9 @@ func (s *Service) findOrCreateGoogleUser(ctx context.Context, info googleUserInf
 	}
 
 	providerUID := info.Sub
+	email := normalizeEmail(info.Email)
 	if info.EmailVerified {
-		if u, err := s.repo.FindByEmail(ctx, info.Email); err == nil {
+		if u, err := s.repo.FindByEmail(ctx, email); err == nil {
 			ident := &model.Identity{ID: id.New(), UserID: u.ID, Provider: model.ProviderGoogle, ProviderUID: &providerUID}
 			if err := s.repo.CreateIdentity(ctx, ident); err != nil {
 				return nil, apperror.NewInternal()
@@ -386,7 +470,7 @@ func (s *Service) findOrCreateGoogleUser(ctx context.Context, info googleUserInf
 		}
 	}
 
-	u := &model.User{ID: id.New(), Email: info.Email, Name: info.Name, AvatarURL: info.Picture, EmailVerified: info.EmailVerified}
+	u := &model.User{ID: id.New(), Email: email, Name: info.Name, AvatarURL: info.Picture, EmailVerified: info.EmailVerified}
 	ident := &model.Identity{ID: id.New(), Provider: model.ProviderGoogle, ProviderUID: &providerUID}
 	if err := s.repo.CreateUserWithIdentity(ctx, u, ident); err != nil {
 		if dberr.IsDuplicate(err) {
@@ -402,7 +486,7 @@ func (s *Service) findOrCreateGoogleUser(ctx context.Context, info googleUserInf
 // password on every deploy), otherwise a new local user+identity is
 // created. Used by cmd/seed only — nothing in the HTTP API calls this.
 func (s *Service) EnsureUser(ctx context.Context, email, password, name string) (*model.User, error) {
-	email = strings.ToLower(strings.TrimSpace(email))
+	email = normalizeEmail(email)
 	if u, err := s.repo.FindByEmail(ctx, email); err == nil {
 		return u, nil
 	}

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

@@ -1,6 +1,7 @@
 package user
 
 import (
+	"fmt"
 	"context"
 	"errors"
 	"net/http"
@@ -15,7 +16,7 @@ import (
 	"gorm.io/gorm"
 )
 
-// fakeTokenStore = in-memory mock of tokenStore, mirroring redisTokenStore's
+// fakeTokenStore = in-memory mock of tokenStore, mirroring the real store's
 // three-map shape (active / used-tombstone / per-user session set) closely
 // enough to exercise rotation + reuse-detection without a real Redis.
 type fakeTokenStore struct {
@@ -82,6 +83,37 @@ func (f *fakeTokenStore) ConsumeEmailVerifyToken(context.Context, string) (uuid.
 // token), the rest just satisfy the interface.
 type fakeRepo struct {
 	user *model.User
+	failures    map[string]int
+	lockedUntil map[string]time.Time
+}
+
+// throttle: the fake keeps the counter in memory so the lockout path can be
+// exercised without a database. Same shape as the real one — a key, a count,
+// and a time — because what the tests care about is when Service decides to
+// stop asking bcrypt anything.
+func (f *fakeRepo) LoginLockedUntil(_ context.Context, key string) (time.Time, error) {
+	return f.lockedUntil[key], nil
+}
+
+func (f *fakeRepo) RecordLoginFailure(_ context.Context, key string, freeAttempts int, maxLock time.Duration) error {
+	if f.lockedUntil == nil {
+		f.lockedUntil = map[string]time.Time{}
+	}
+	f.failures[key]++
+	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
+}
+
+func (f *fakeRepo) ClearLoginFailures(_ context.Context, key string) error {
+	delete(f.failures, key)
+	delete(f.lockedUntil, key)
+	return nil
 }
 
 func (f *fakeRepo) FindByEmail(context.Context, string) (*model.User, error) {
@@ -107,7 +139,7 @@ func (f *fakeRepo) UpdateIdentity(context.Context, *model.Identity) error
 
 type fakeMailer struct{}
 
-func (fakeMailer) Send(string, string, string) error { return nil }
+func (fakeMailer) Send(context.Context, string, string, string) error { return nil }
 
 // go-scaffold:user-service-test-types
 
@@ -235,3 +267,50 @@ func TestService_LogoutAll_RevokesEverySessionButLeavesOthersAlone(t *testing.T)
 		t.Fatal("expected a different user's session to be untouched by LogoutAll")
 	}
 }
+
+// The control that actually stops credential stuffing: the counter follows the
+// account, so spreading attempts across a proxy pool doesn't help.
+func TestService_Login_LocksTheAccountAfterRepeatedFailures(t *testing.T) {
+	repo := &fakeRepo{
+		user:     &model.User{ID: uuid.New(), Email: "a@example.com"},
+		failures: map[string]int{},
+	}
+	svc := newTestService(repo, newFakeTokenStore())
+	in := loginInput{Email: "a@example.com", Password: "wrong"}
+
+	// the free attempts answer "wrong password", not "locked"
+	for i := 0; i < loginFreeAttempts; i++ {
+		if _, err := svc.Login(context.Background(), in); 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))
+		}
+	}
+
+	// the next one trips the lock...
+	if _, err := svc.Login(context.Background(), in); 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" {
+		t.Fatalf("expected AUTH_TOO_MANY_ATTEMPTS once locked, 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) {
+	if throttleKey("login", "a@example.com") == throttleKey("pwreset", "a@example.com") {
+		t.Fatal("login and password-reset share a throttle key; a locked login would block recovery")
+	}
+}
+
+// code pulls the AppError code out, so a test asserting on behaviour doesn't
+// have to care how the error is wrapped.
+func code(err error) string {
+	var appErr *apperror.AppError
+	if errors.As(err, &appErr) {
+		return appErr.Code
+	}
+	return fmt.Sprintf("%v", err)
+}

package/templates/add/auth/internal/app/user/tokenstore.go.hbs

@@ -5,19 +5,17 @@ import (
 	"time"
 
 	"github.com/google/uuid"
-	"github.com/redis/go-redis/v9"
 )
 
-const (
-	refreshKeyPrefix     = "user:refresh:"      // +hash -> userID, TTL = refreshTTL
-	refreshUserKeyPrefix = "user:refresh:user:"  // +userID -> SET of active token hashes
-	refreshUsedKeyPrefix = "user:refresh:used:"  // +hash -> userID, TTL = refreshTTL (reuse-detection tombstone)
-	pwresetKeyPrefix     = "user:pwreset:"       // +hash -> userID, TTL = resetTTL, GETDEL on consume
-	emailVerifyKeyPrefix = "user:emailverify:"   // +hash -> userID, TTL = emailVerifyTTL, GETDEL on consume
-)
-
-// tokenStore is what Service needs from Redis for refresh tokens — declared
-// consumer-side so it can be faked in tests without a real Redis.
+// tokenStore is the short-lived-token surface Service needs — declared
+// consumer-side so it can be faked in tests, and so the backing store is a
+// choice rather than a hard dependency. Two implementations ship with the
+// scaffold and exactly one is written into a project:
+//
+//   `add auth --store postgres`  ->  tokenstore_pg.go     (default, no extra service)
+//   `add auth --store redis`     ->  tokenstore_redis.go  (exact across pods)
+//
+// Service never learns which one it got.
 type tokenStore interface {
 	SetRefreshToken(ctx context.Context, tokenHash string, userID uuid.UUID, ttl time.Duration) error
 	GetRefreshToken(ctx context.Context, tokenHash string) (uuid.UUID, bool, error)
@@ -30,130 +28,3 @@ type tokenStore interface {
 	SetEmailVerifyToken(ctx context.Context, tokenHash string, userID uuid.UUID, ttl time.Duration) error
 	ConsumeEmailVerifyToken(ctx context.Context, tokenHash string) (uuid.UUID, bool, error)
 }
-
-type redisTokenStore struct {
-	rdb *redis.Client
-}
-
-func NewRedisTokenStore(rdb *redis.Client) *redisTokenStore {
-	return &redisTokenStore{rdb: rdb}
-}
-
-func (s *redisTokenStore) SetRefreshToken(ctx context.Context, tokenHash string, userID uuid.UUID, ttl time.Duration) error {
-	pipe := s.rdb.TxPipeline()
-	pipe.Set(ctx, refreshKeyPrefix+tokenHash, userID.String(), ttl)
-	pipe.SAdd(ctx, refreshUserKeyPrefix+userID.String(), tokenHash)
-	_, err := pipe.Exec(ctx)
-	return err
-}
-
-func (s *redisTokenStore) GetRefreshToken(ctx context.Context, tokenHash string) (uuid.UUID, bool, error) {
-	raw, err := s.rdb.Get(ctx, refreshKeyPrefix+tokenHash).Result()
-	if err == redis.Nil {
-		return uuid.Nil, false, nil
-	}
-	if err != nil {
-		return uuid.Nil, false, err
-	}
-	id, err := uuid.Parse(raw)
-	if err != nil {
-		return uuid.Nil, false, err
-	}
-	return id, true, nil
-}
-
-func (s *redisTokenStore) DeleteRefreshToken(ctx context.Context, tokenHash string, userID uuid.UUID) error {
-	pipe := s.rdb.TxPipeline()
-	pipe.Del(ctx, refreshKeyPrefix+tokenHash)
-	pipe.SRem(ctx, refreshUserKeyPrefix+userID.String(), tokenHash)
-	_, err := pipe.Exec(ctx)
-	return err
-}
-
-// RevokeAllRefreshTokens walks the per-user session set and deletes every
-// active refresh token for that user — used when reuse of an already-rotated
-// token is detected (see Service.Refresh): that means the raw token leaked,
-// so every session, not just the replayed one, is treated as compromised.
-//
-// ponytail: the per-user set has no per-member TTL cleanup of its own — a
-// member outlives its key's TTL as a stale entry until the next revoke or
-// rotation touches it. Self-heals over time; revisit if a single user's
-// session count grows large enough to matter.
-func (s *redisTokenStore) RevokeAllRefreshTokens(ctx context.Context, userID uuid.UUID) error {
-	setKey := refreshUserKeyPrefix + userID.String()
-	hashes, err := s.rdb.SMembers(ctx, setKey).Result()
-	if err != nil {
-		return err
-	}
-	if len(hashes) == 0 {
-		return nil
-	}
-	pipe := s.rdb.TxPipeline()
-	for _, h := range hashes {
-		pipe.Del(ctx, refreshKeyPrefix+h)
-	}
-	pipe.Del(ctx, setKey)
-	_, err = pipe.Exec(ctx)
-	return err
-}
-
-func (s *redisTokenStore) MarkRefreshTokenUsed(ctx context.Context, tokenHash string, userID uuid.UUID, ttl time.Duration) error {
-	return s.rdb.Set(ctx, refreshUsedKeyPrefix+tokenHash, userID.String(), ttl).Err()
-}
-
-func (s *redisTokenStore) IsRefreshTokenUsed(ctx context.Context, tokenHash string) (uuid.UUID, bool, error) {
-	raw, err := s.rdb.Get(ctx, refreshUsedKeyPrefix+tokenHash).Result()
-	if err == redis.Nil {
-		return uuid.Nil, false, nil
-	}
-	if err != nil {
-		return uuid.Nil, false, err
-	}
-	id, err := uuid.Parse(raw)
-	if err != nil {
-		return uuid.Nil, false, err
-	}
-	return id, true, nil
-}
-
-func (s *redisTokenStore) SetPasswordResetToken(ctx context.Context, tokenHash string, userID uuid.UUID, ttl time.Duration) error {
-	return s.rdb.Set(ctx, pwresetKeyPrefix+tokenHash, userID.String(), ttl).Err()
-}
-
-// ConsumePasswordResetToken is one-time-use by construction: GETDEL is
-// atomic, so a token can't be raced into being consumed twice.
-func (s *redisTokenStore) ConsumePasswordResetToken(ctx context.Context, tokenHash string) (uuid.UUID, bool, error) {
-	raw, err := s.rdb.GetDel(ctx, pwresetKeyPrefix+tokenHash).Result()
-	if err == redis.Nil {
-		return uuid.Nil, false, nil
-	}
-	if err != nil {
-		return uuid.Nil, false, err
-	}
-	id, err := uuid.Parse(raw)
-	if err != nil {
-		return uuid.Nil, false, err
-	}
-	return id, true, nil
-}
-
-func (s *redisTokenStore) SetEmailVerifyToken(ctx context.Context, tokenHash string, userID uuid.UUID, ttl time.Duration) error {
-	return s.rdb.Set(ctx, emailVerifyKeyPrefix+tokenHash, userID.String(), ttl).Err()
-}
-
-// ConsumeEmailVerifyToken is one-time-use by construction, same as
-// ConsumePasswordResetToken — GETDEL is atomic.
-func (s *redisTokenStore) ConsumeEmailVerifyToken(ctx context.Context, tokenHash string) (uuid.UUID, bool, error) {
-	raw, err := s.rdb.GetDel(ctx, emailVerifyKeyPrefix+tokenHash).Result()
-	if err == redis.Nil {
-		return uuid.Nil, false, nil
-	}
-	if err != nil {
-		return uuid.Nil, false, err
-	}
-	id, err := uuid.Parse(raw)
-	if err != nil {
-		return uuid.Nil, false, err
-	}
-	return id, true, nil
-}