@nakedev/go-scaffold 0.3.3 → 0.4.3

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

@@ -0,0 +1,199 @@
+package user
+
+import (
+	"context"
+	"strings"
+	"testing"
+	"time"
+
+	"{{goModule}}/internal/app/user/model"
+	"{{goModule}}/internal/shared/apperror"
+
+	"github.com/google/uuid"
+)
+
+const testMFAEncryptionKey = "MDEyMzQ1Njc4OWFiY2RlZjAxMjM0NTY3ODlhYmNkZWY="
+
+func configuredMFATestService(t *testing.T) (*Service, *fakeMFAStore, uuid.UUID, time.Time) {
+	t.Helper()
+	userID := uuid.New()
+	mfa := newFakeMFAStore()
+	svc := newTestService(&fakeRepo{user: &model.User{ID: userID, Email: "mfa@example.com"}}, newFakeTokenStore())
+	now := time.Now()
+	svc.mfa = mfa
+	svc.now = func() time.Time { return now }
+	svc.config.MFA = MFASettings{
+		Enabled:           true,
+		Issuer:            "Example",
+		EncryptionKey:     testMFAEncryptionKey,
+		ChallengeTTL:      5 * time.Minute,
+		TOTPWindow:        1,
+		RecoveryCodeCount: 10,
+	}
+	return svc, mfa, userID, now
+}
+
+func TestTOTPCodeMatchesRFC6238SHA1Vector(t *testing.T) {
+	secret := "GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ"
+	code, err := totpCode(secret, time.Unix(59, 0))
+	if err != nil {
+		t.Fatalf("generate TOTP: %v", err)
+	}
+	if code != "287082" {
+		t.Fatalf("expected RFC 6238 six-digit code 287082, got %s", code)
+	}
+}
+
+func TestMFADefaultIsDisabled(t *testing.T) {
+	userID := uuid.New()
+	svc := newTestService(&fakeRepo{user: &model.User{ID: userID, Email: "default@example.com"}}, newFakeTokenStore())
+
+	status, err := svc.MFAStatus(context.Background(), userID)
+	if err != nil {
+		t.Fatalf("read default MFA status: %v", err)
+	}
+	if status.Available || status.Enabled {
+		t.Fatalf("MFA must be disabled and unavailable by default: %+v", status)
+	}
+}
+
+func TestValidateMFASettingsRejectsUnsafeEnabledConfiguration(t *testing.T) {
+	valid := MFASettings{
+		Enabled:           true,
+		EncryptionKey:     testMFAEncryptionKey,
+		ChallengeTTL:      5 * time.Minute,
+		TOTPWindow:        1,
+		RecoveryCodeCount: 10,
+	}
+	if err := ValidateMFASettings(valid); err != nil {
+		t.Fatalf("valid MFA settings rejected: %v", err)
+	}
+
+	for name, settings := range map[string]MFASettings{
+		"missing encryption key":  validWithMFAOverride(valid, func(s *MFASettings) { s.EncryptionKey = "" }),
+		"non-positive challenge":  validWithMFAOverride(valid, func(s *MFASettings) { s.ChallengeTTL = 0 }),
+		"wide TOTP window":        validWithMFAOverride(valid, func(s *MFASettings) { s.TOTPWindow = 4 }),
+		"too few recovery codes":  validWithMFAOverride(valid, func(s *MFASettings) { s.RecoveryCodeCount = 4 }),
+		"too many recovery codes": validWithMFAOverride(valid, func(s *MFASettings) { s.RecoveryCodeCount = 21 }),
+	} {
+		if err := ValidateMFASettings(settings); err == nil {
+			t.Errorf("%s: expected invalid enabled configuration to fail", name)
+		}
+	}
+	if err := ValidateMFASettings(MFASettings{Enabled: false}); err != nil {
+		t.Fatalf("disabled MFA should not require an encryption key: %v", err)
+	}
+}
+
+func validWithMFAOverride(base MFASettings, override func(*MFASettings)) MFASettings {
+	copy := base
+	override(&copy)
+	return copy
+}
+
+func TestMFAEnrollmentIsPendingUntilTOTPConfirmation(t *testing.T) {
+	svc, store, userID, now := configuredMFATestService(t)
+	ctx := context.Background()
+
+	setup, err := svc.SetupMFA(ctx, userID)
+	if err != nil {
+		t.Fatalf("setup MFA: %v", err)
+	}
+	if setup.Secret == "" || !strings.HasPrefix(setup.OTPAuthURI, "otpauth://totp/") {
+		t.Fatalf("unexpected setup response: %+v", setup)
+	}
+	if strings.Contains(store.enrollments[userID].EncryptedSecret, setup.Secret) {
+		t.Fatal("MFA secret must not be stored in plaintext")
+	}
+
+	status, err := svc.MFAStatus(ctx, userID)
+	if err != nil || !status.Available || status.Enabled {
+		t.Fatalf("expected available but disabled pending enrollment: %+v, %v", status, err)
+	}
+	code, _ := totpCode(setup.Secret, now)
+	codes, err := svc.ConfirmMFA(ctx, userID, code)
+	if err != nil {
+		t.Fatalf("confirm MFA: %v", err)
+	}
+	if len(codes) != 10 {
+		t.Fatalf("expected 10 recovery codes, got %d", len(codes))
+	}
+	status, err = svc.MFAStatus(ctx, userID)
+	if err != nil || !status.Enabled {
+		t.Fatalf("expected enabled MFA status: %+v, %v", status, err)
+	}
+}
+
+func TestMFAChallengeIsRequiredAndOneUse(t *testing.T) {
+	svc, _, userID, now := configuredMFATestService(t)
+	ctx := context.Background()
+	secret, err := newTOTPSecret()
+	if err != nil {
+		t.Fatalf("secret: %v", err)
+	}
+	encrypted, err := encryptMFASecret(testMFAEncryptionKey, secret)
+	if err != nil {
+		t.Fatalf("encrypt: %v", err)
+	}
+	if err := svc.mfa.ConfirmEnrollment(ctx, userID, encrypted, []string{}); err == nil {
+		t.Fatal("expected store to reject an enrollment without recovery codes")
+	}
+	// Use the service path so the exact recovery-code policy is exercised.
+	if err := svc.mfa.PutPendingEnrollment(ctx, userID, encrypted); err != nil {
+		t.Fatalf("pending: %v", err)
+	}
+	code, _ := totpCode(secret, now)
+	if _, err := svc.ConfirmMFA(ctx, userID, code); err != nil {
+		t.Fatalf("confirm: %v", err)
+	}
+
+	result, err := svc.completeLogin(ctx, &model.User{ID: userID, Email: "mfa@example.com"})
+	if err != nil || result.MFAChallenge == "" || result.authResponse != nil {
+		t.Fatalf("expected pre-session MFA challenge: %+v, %v", result, err)
+	}
+	auth, err := svc.VerifyMFA(ctx, result.MFAChallenge, code)
+	if err != nil || auth == nil || auth.AccessToken == "" || auth.RefreshToken == "" {
+		t.Fatalf("verify MFA: %+v, %v", auth, err)
+	}
+	if _, err := svc.VerifyMFA(ctx, result.MFAChallenge, code); codeOfMFAError(err) != "AUTH_MFA_INVALID" {
+		t.Fatalf("expected one-use challenge rejection, got %v", err)
+	}
+}
+
+func TestMFARecoveryCodeIsOneUse(t *testing.T) {
+	svc, _, userID, now := configuredMFATestService(t)
+	ctx := context.Background()
+	setup, err := svc.SetupMFA(ctx, userID)
+	if err != nil {
+		t.Fatalf("setup: %v", err)
+	}
+	code, _ := totpCode(setup.Secret, now)
+	recoveryCodes, err := svc.ConfirmMFA(ctx, userID, code)
+	if err != nil {
+		t.Fatalf("confirm: %v", err)
+	}
+	result, err := svc.completeLogin(ctx, &model.User{ID: userID, Email: "mfa@example.com"})
+	if err != nil {
+		t.Fatalf("login challenge: %v", err)
+	}
+	if _, err := svc.VerifyMFA(ctx, result.MFAChallenge, recoveryCodes[0]); err != nil {
+		t.Fatalf("verify with recovery code: %v", err)
+	}
+	result, err = svc.completeLogin(ctx, &model.User{ID: userID, Email: "mfa@example.com"})
+	if err != nil {
+		t.Fatalf("second login challenge: %v", err)
+	}
+	if _, err := svc.VerifyMFA(ctx, result.MFAChallenge, recoveryCodes[0]); codeOfMFAError(err) != "AUTH_MFA_INVALID" {
+		t.Fatalf("expected consumed recovery code rejection, got %v", err)
+	}
+}
+
+func codeOfMFAError(err error) string {
+	if err == nil {
+		return ""
+	}
+	if appErr, ok := err.(*apperror.AppError); ok {
+		return appErr.Code
+	}
+	return ""
+}

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

@@ -0,0 +1,127 @@
+package user
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"fmt"
+	"time"
+
+	"{{goModule}}/internal/app/user/model"
+	"{{goModule}}/internal/shared/tx"
+
+	"github.com/google/uuid"
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+)
+
+// PostgresMFAStore is intentionally independent of the selected refresh-token
+// adapter. MFA challenges and recovery codes need durable, atomic semantics in
+// every deployment, including Redis-backed auth behind multiple replicas.
+type PostgresMFAStore struct {
+	db *gorm.DB
+}
+
+func NewPostgresMFAStore(db *gorm.DB) *PostgresMFAStore { return &PostgresMFAStore{db: db} }
+
+func (s *PostgresMFAStore) GetEnrollment(ctx context.Context, userID uuid.UUID) (MFAEnrollment, bool, error) {
+	var row model.MFAEnrollment
+	err := tx.From(ctx, s.db).WithContext(ctx).First(&row, "user_id = ?", userID).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return MFAEnrollment{}, false, nil
+	}
+	if err != nil {
+		return MFAEnrollment{}, false, err
+	}
+	return MFAEnrollment{EncryptedSecret: row.EncryptedSecret, Enabled: row.Enabled}, true, nil
+}
+
+func (s *PostgresMFAStore) PutPendingEnrollment(ctx context.Context, userID uuid.UUID, encryptedSecret string) error {
+	if userID == uuid.Nil || encryptedSecret == "" {
+		return errors.New("MFA enrollment is incomplete")
+	}
+	row := model.MFAEnrollment{UserID: userID, EncryptedSecret: encryptedSecret, Enabled: false}
+	return tx.From(ctx, s.db).WithContext(ctx).
+		Where("user_id = ? AND enabled = ?", userID, false).
+		Assign(map[string]any{"encrypted_secret": encryptedSecret, "enabled": false, "updated_at": time.Now()}).
+		FirstOrCreate(&row).Error
+}
+
+func (s *PostgresMFAStore) ConfirmEnrollment(ctx context.Context, userID uuid.UUID, encryptedSecret string, recoveryCodeHashes []string) error {
+	if userID == uuid.Nil || encryptedSecret == "" || len(recoveryCodeHashes) == 0 {
+		return errors.New("MFA enrollment confirmation is incomplete")
+	}
+	return tx.From(ctx, s.db).WithContext(ctx).Transaction(func(db *gorm.DB) error {
+		var enrollment model.MFAEnrollment
+		if err := db.Clauses(clause.Locking{Strength: "UPDATE"}).Where("user_id = ?", userID).First(&enrollment).Error; err != nil {
+			return err
+		}
+		if enrollment.Enabled {
+			return errors.New("MFA enrollment is already enabled")
+		}
+		if err := db.Model(&enrollment).Updates(map[string]any{
+			"encrypted_secret": encryptedSecret,
+			"enabled":          true,
+			"updated_at":       time.Now(),
+		}).Error; err != nil {
+			return err
+		}
+		if err := db.Where("user_id = ?", userID).Delete(&model.MFARecoveryCode{}).Error; err != nil {
+			return err
+		}
+		rows := make([]model.MFARecoveryCode, len(recoveryCodeHashes))
+		for i, hash := range recoveryCodeHashes {
+			rows[i] = model.MFARecoveryCode{UserID: userID, CodeHash: hash}
+		}
+		return db.Create(&rows).Error
+	})
+}
+
+func (s *PostgresMFAStore) Disable(ctx context.Context, userID uuid.UUID) error {
+	return tx.From(ctx, s.db).WithContext(ctx).Transaction(func(db *gorm.DB) error {
+		if err := db.Where("user_id = ?", userID).Delete(&model.MFARecoveryCode{}).Error; err != nil {
+			return err
+		}
+		return db.Where("user_id = ?", userID).Delete(&model.MFAEnrollment{}).Error
+	})
+}
+
+func (s *PostgresMFAStore) CreateChallenge(ctx context.Context, hash string, challenge MFAChallenge) error {
+	if hash == "" || challenge.UserID == uuid.Nil || !challenge.ExpiresAt.After(time.Now()) {
+		return fmt.Errorf("MFA challenge is invalid")
+	}
+	row := model.MFAChallenge{ChallengeHash: hash, UserID: challenge.UserID, ExpiresAt: challenge.ExpiresAt}
+	return tx.From(ctx, s.db).WithContext(ctx).Create(&row).Error
+}
+
+func (s *PostgresMFAStore) ConsumeChallenge(ctx context.Context, hash string) (MFAChallenge, bool, error) {
+	var challenge MFAChallenge
+	err := tx.From(ctx, s.db).WithContext(ctx).Raw(
+		`DELETE FROM user_svc.mfa_challenges
+		 WHERE challenge_hash = ? AND expires_at > now()
+		 RETURNING user_id, expires_at`, hash,
+	).Row().Scan(&challenge.UserID, &challenge.ExpiresAt)
+	if errors.Is(err, sql.ErrNoRows) {
+		return MFAChallenge{}, false, nil
+	}
+	if err != nil {
+		return MFAChallenge{}, false, err
+	}
+	return challenge, true, nil
+}
+
+func (s *PostgresMFAStore) ConsumeRecoveryCode(ctx context.Context, userID uuid.UUID, hash string) (bool, error) {
+	var consumed string
+	err := tx.From(ctx, s.db).WithContext(ctx).Raw(
+		`DELETE FROM user_svc.mfa_recovery_codes
+		 WHERE user_id = ? AND code_hash = ?
+		 RETURNING code_hash`, userID, hash,
+	).Row().Scan(&consumed)
+	if errors.Is(err, sql.ErrNoRows) {
+		return false, nil
+	}
+	if err != nil {
+		return false, err
+	}
+	return consumed != "", nil
+}

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

@@ -0,0 +1,174 @@
+package user
+
+import (
+	"context"
+	"os"
+	"sync"
+	"testing"
+	"time"
+
+	"{{goModule}}/internal/app/user/model"
+
+	"github.com/google/uuid"
+	"gorm.io/driver/postgres"
+	"gorm.io/gorm"
+)
+
+// mfaStoreDBForTest opens the same versioned-migration database used by
+// production. This is intentionally separate from the unit fake: the
+// one-use guarantees depend on PostgreSQL's row-level atomicity.
+func mfaStoreDBForTest(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("MFA store 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 MFA store database: %v", err)
+		}
+		t.Skipf("MFA store integration test skipped: %v", err)
+	}
+	sqlDB, err := db.DB()
+	if err != nil {
+		t.Fatalf("get MFA store SQL handle: %v", err)
+	}
+	if err := sqlDB.Ping(); err != nil {
+		if os.Getenv("REQUIRE_TEST_DB") == "true" {
+			t.Fatalf("ping required MFA store database: %v", err)
+		}
+		t.Skipf("MFA store integration test skipped: %v", err)
+	}
+	t.Cleanup(func() { _ = sqlDB.Close() })
+	return db
+}
+
+func TestPostgresMFAStore_ConsumesChallengesAndRecoveryCodesOnce(t *testing.T) {
+	db := mfaStoreDBForTest(t)
+	store := NewPostgresMFAStore(db)
+	ctx := context.Background()
+	userID := uuid.New()
+	if err := db.Create(&model.User{ID: userID, Email: "mfa-store-" + uuid.NewString() + "@example.com"}).Error; err != nil {
+		t.Fatalf("create test user: %v", err)
+	}
+	t.Cleanup(func() { _ = db.Delete(&model.User{}, "id = ?", userID).Error })
+
+	if err := store.PutPendingEnrollment(ctx, userID, "encrypted-secret"); err != nil {
+		t.Fatalf("put pending enrollment: %v", err)
+	}
+	enrollment, found, err := store.GetEnrollment(ctx, userID)
+	if err != nil || !found || enrollment.Enabled {
+		t.Fatalf("expected pending enrollment, got found=%t enrollment=%+v err=%v", found, enrollment, err)
+	}
+
+	const recoveryHash = "recovery-hash-real-pg"
+	if err := store.ConfirmEnrollment(ctx, userID, enrollment.EncryptedSecret, []string{recoveryHash}); err != nil {
+		t.Fatalf("confirm enrollment: %v", err)
+	}
+	enrollment, found, err = store.GetEnrollment(ctx, userID)
+	if err != nil || !found || !enrollment.Enabled {
+		t.Fatalf("expected enabled enrollment, got found=%t enrollment=%+v err=%v", found, enrollment, err)
+	}
+
+	challengeHash := "challenge-hash-real-pg-" + uuid.NewString()
+	if err := store.CreateChallenge(ctx, challengeHash, MFAChallenge{UserID: userID, ExpiresAt: time.Now().Add(time.Minute)}); err != nil {
+		t.Fatalf("create challenge: %v", err)
+	}
+	consumeChallengeConcurrently(t, store, challengeHash, userID)
+
+	consumeRecoveryCodeConcurrently(t, store, userID, recoveryHash)
+	if err := store.Disable(ctx, userID); err != nil {
+		t.Fatalf("disable MFA: %v", err)
+	}
+	if _, found, err := store.GetEnrollment(ctx, userID); err != nil || found {
+		t.Fatalf("expected disable to remove enrollment, found=%t err=%v", found, err)
+	}
+}
+
+func consumeChallengeConcurrently(t *testing.T, store *PostgresMFAStore, hash string, wantUser uuid.UUID) {
+	t.Helper()
+	const callers = 16
+	start := make(chan struct{})
+	results := make(chan struct {
+		challenge MFAChallenge
+		found     bool
+		err       error
+	}, callers)
+	var wg sync.WaitGroup
+	for i := 0; i < callers; i++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			<-start
+			challenge, found, err := store.ConsumeChallenge(context.Background(), hash)
+			results <- struct {
+				challenge MFAChallenge
+				found     bool
+				err       error
+			}{challenge: challenge, found: found, err: err}
+		}()
+	}
+	close(start)
+	wg.Wait()
+	close(results)
+
+	winners := 0
+	for result := range results {
+		if result.err != nil {
+			t.Fatalf("concurrent challenge consume: %v", result.err)
+		}
+		if result.found {
+			winners++
+			if result.challenge.UserID != wantUser {
+				t.Fatalf("challenge winner returned user %s, want %s", result.challenge.UserID, wantUser)
+			}
+		}
+	}
+	if winners != 1 {
+		t.Fatalf("expected exactly one real-database challenge winner, got %d", winners)
+	}
+}
+
+func consumeRecoveryCodeConcurrently(t *testing.T, store *PostgresMFAStore, userID uuid.UUID, hash string) {
+	t.Helper()
+	const callers = 16
+	start := make(chan struct{})
+	results := make(chan struct {
+		used bool
+		err  error
+	}, callers)
+	var wg sync.WaitGroup
+	for i := 0; i < callers; i++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			<-start
+			used, err := store.ConsumeRecoveryCode(context.Background(), userID, hash)
+			results <- struct {
+				used bool
+				err  error
+			}{used: used, err: err}
+		}()
+	}
+	close(start)
+	wg.Wait()
+	close(results)
+
+	winners := 0
+	for result := range results {
+		if result.err != nil {
+			t.Fatalf("concurrent recovery-code consume: %v", result.err)
+		}
+		if result.used {
+			winners++
+		}
+	}
+	if winners != 1 {
+		t.Fatalf("expected exactly one real-database recovery-code winner, got %d", winners)
+	}
+}

package/templates/add/auth/internal/app/user/model/authtoken.go.hbs

@@ -24,8 +24,8 @@ import (
 // gets a plain rejection instead of tripping reuse detection and nuking every
 // session the user has.
 //
-// No foreign key to users on purpose: GORM's AutoMigrate (dev) wouldn't create
-// one from these tags, and a constraint that exists in production but not in
+// No foreign key to users on purpose: the development bootstrap wouldn't
+// create one from these tags, and a constraint that exists in production but not in
 // development is the exact mismatch that stops the app booting. A token whose
 // user is gone simply fails the lookup that follows.
 type AuthToken struct {
@@ -33,6 +33,12 @@ type AuthToken struct {
 	UserID    uuid.UUID `gorm:"type:uuid;not null;index:idx_auth_tokens_user_kind,priority:1"`
 	Kind      string    `gorm:"type:varchar(20);not null;index:idx_auth_tokens_user_kind,priority:2"`
 	ExpiresAt time.Time `gorm:"not null;index:idx_auth_tokens_expires_at"`
+	// AbsoluteExpiresAt is set only for refresh tokens. Recovery tokens and
+	// OAuth transactions have no sliding lifetime, so it remains nil there.
+	AbsoluteExpiresAt *time.Time `gorm:"index:idx_auth_tokens_absolute_expires_at"`
+	Provider          string     `gorm:"type:varchar(20);not null;default:''"`
+	CodeChallenge     string     `gorm:"type:text;not null;default:''"`
+	Nonce             string     `gorm:"type:text;not null;default:''"`
 	CreatedAt time.Time
 }
 

package/templates/add/auth/internal/app/user/model/identity.go.hbs

@@ -14,9 +14,10 @@ const (
 )
 
 // Identity = how you log in (one row per login method). PasswordHash is set
-// for a "local" identity; ProviderUID is set for "google" (the provider's own
-// subject id). Split from User so adding a login method never touches the
-// profile row — one person can have both and resolve to the same account.
+// for a "local" identity; ProviderUID is set for an external provider (the
+// provider's own stable subject id). Split from User so adding a login method
+// never touches the profile row — one person can have several methods and
+// resolve to the same account.
 type Identity struct {
 	ID           uuid.UUID `json:"id" gorm:"type:uuid;primaryKey"`
 	UserID       uuid.UUID `json:"user_id" gorm:"type:uuid;not null;uniqueIndex:idx_identities_user_provider,priority:1"`

package/templates/add/auth/internal/app/user/model/mfa_challenge.go.hbs

@@ -0,0 +1,17 @@
+package model
+
+import (
+	"time"
+
+	"github.com/google/uuid"
+)
+
+// MFAChallenge is a one-use pre-session challenge. Only its hash is stored.
+type MFAChallenge struct {
+	ChallengeHash string    `gorm:"type:text;primaryKey"`
+	UserID        uuid.UUID `gorm:"type:uuid;not null;index:idx_mfa_challenges_user"`
+	ExpiresAt     time.Time `gorm:"not null;index:idx_mfa_challenges_expires_at"`
+	CreatedAt     time.Time
+}
+
+func (MFAChallenge) TableName() string { return "user_svc.mfa_challenges" }

package/templates/add/auth/internal/app/user/model/mfa_enrollment.go.hbs

@@ -0,0 +1,20 @@
+package model
+
+import (
+	"time"
+
+	"github.com/google/uuid"
+)
+
+// MFAEnrollment stores one user's TOTP enrollment. The secret is encrypted by
+// the application before it reaches this model; plaintext secrets never live
+// in the database.
+type MFAEnrollment struct {
+	UserID          uuid.UUID `gorm:"type:uuid;primaryKey"`
+	EncryptedSecret string    `gorm:"type:text;not null"`
+	Enabled         bool      `gorm:"not null;default:false"`
+	CreatedAt       time.Time
+	UpdatedAt       time.Time
+}
+
+func (MFAEnrollment) TableName() string { return "user_svc.mfa_enrollments" }

package/templates/add/auth/internal/app/user/model/mfa_recovery_code.go.hbs

@@ -0,0 +1,17 @@
+package model
+
+import (
+	"time"
+
+	"github.com/google/uuid"
+)
+
+// MFARecoveryCode stores a hash only. A consumed code is deleted atomically,
+// so the table never becomes a second mutable session state machine.
+type MFARecoveryCode struct {
+	UserID    uuid.UUID `gorm:"type:uuid;primaryKey;index:idx_mfa_recovery_codes_user"`
+	CodeHash  string    `gorm:"type:text;primaryKey"`
+	CreatedAt time.Time
+}
+
+func (MFARecoveryCode) TableName() string { return "user_svc.mfa_recovery_codes" }

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

@@ -13,8 +13,9 @@ import (
 type User struct {
 	ID            uuid.UUID `json:"id" gorm:"type:uuid;primaryKey"`
 	// index named explicitly, and named the same in create_users.up.sql: an
-	// anonymous `uniqueIndex` makes GORM invent one, and AutoMigrate then
-	// tries to DROP the differently-named constraint the migration created.
+	// anonymous `uniqueIndex` makes GORM invent one, and the development
+	// bootstrap then tries to DROP the differently-named constraint the
+	// migration created.
 	Email         string    `json:"email" gorm:"uniqueIndex:idx_users_email;not null"`
 	Name          string    `json:"name"`
 	AvatarURL     string    `json:"avatar_url"`