@nakedev/go-scaffold 0.4.0 → 0.5.0

package/templates/add/auth/internal/app/user/adapters/inbound/http/handler_test.go.hbs

@@ -0,0 +1,311 @@
+package httpadapter
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/base64"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"strings"
+	"testing"
+	"time"
+
+	"{{goModule}}/internal/app/user/application"
+	"{{goModule}}/internal/shared/middleware"
+
+	"github.com/gin-gonic/gin"
+)
+
+type allowAllLimiter struct{}
+
+func (allowAllLimiter) Allow(_ context.Context, _ string, _ int, _ time.Duration) bool { return true }
+
+type allowAllAuthorizer struct{}
+
+func (allowAllAuthorizer) Require(_ string) gin.HandlerFunc {
+	return func(c *gin.Context) { c.Next() }
+}
+
+const handlerOAuthVerifier = "client-code-verifier-0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ"
+
+type stubService struct {
+	application.ServicePort
+}
+
+func (stubService) BeginLogin(_ context.Context, provider string, in application.LoginStartInput) (*application.Authorization, error) {
+	if provider != "fake" {
+		return nil, application.NewOAuthError(application.OAuthProviderUnavailable, nil)
+	}
+	return &application.Authorization{URL: "https://provider.example.test/authorize?" + url.Values{
+		"state":                 {in.State},
+		"code_challenge":        {in.CodeChallenge},
+		"code_challenge_method": {in.CodeChallengeMethod},
+	}.Encode()}, nil
+}
+
+func (stubService) ExchangeLogin(_ context.Context, provider string, in application.LoginExchangeInput) (*application.AuthResult, error) {
+	if provider != "fake" {
+		return nil, application.NewOAuthError(application.OAuthProviderUnavailable, nil)
+	}
+	if in.State == "" || in.CodeVerifier == "" {
+		return nil, application.NewOAuthError(application.OAuthStateInvalid, nil)
+	}
+	if in.Code == "" {
+		return nil, application.NewOAuthError(application.OAuthFailed, nil)
+	}
+	return application.TokenResult(&application.AuthResponse{
+		AccessToken:  "access-token",
+		RefreshToken: "refresh-token",
+		TokenType:    "Bearer",
+		ExpiresIn:    900,
+	}), nil
+}
+
+func (stubService) Logout(context.Context, string) error { return nil }
+
+func pkceChallenge(verifier string) string {
+	sum := sha256.Sum256([]byte(verifier))
+	return base64.RawURLEncoding.EncodeToString(sum[:])
+}
+
+func newOAuthTestRouter(t *testing.T) *gin.Engine {
+	t.Helper()
+	svc := stubService{}
+	h := NewHandler(svc, "test-secret", time.Hour, true, "strict", allowAllLimiter{}, allowAllAuthorizer{})
+	gin.SetMode(gin.TestMode)
+	router := gin.New()
+	router.Use(middleware.Error(false))
+	h.Register(router)
+	return router
+}
+
+func newCrossSiteTestRouter(t *testing.T) *gin.Engine {
+	t.Helper()
+	svc := stubService{}
+	h := NewHandlerWithOrigins(svc, "test-secret", time.Hour, true, "none", []string{"https://app.example.test"}, allowAllLimiter{}, allowAllAuthorizer{})
+	router := gin.New()
+	router.Use(middleware.Error(false))
+	h.Register(router)
+	return router
+}
+
+func beginOAuthFlow(t *testing.T, router *gin.Engine) (string, string) {
+	t.Helper()
+	const state = "client-state"
+	const verifier = handlerOAuthVerifier
+	request := httptest.NewRequest(http.MethodGet, "/auth/fake/login?"+url.Values{
+		"state":                 {state},
+		"code_challenge":        {pkceChallenge(verifier)},
+		"code_challenge_method": {"S256"},
+	}.Encode(), nil)
+	response := httptest.NewRecorder()
+	router.ServeHTTP(response, request)
+	if response.Code != http.StatusFound {
+		t.Fatalf("login status = %d, want 302; body=%s", response.Code, response.Body.String())
+	}
+	if cookies := response.Result().Cookies(); len(cookies) != 0 {
+		t.Fatalf("client-owned callback must not set a server OAuth state cookie: %#v", cookies)
+	}
+	location, err := url.Parse(response.Header().Get("Location"))
+	if err != nil {
+		t.Fatalf("parse provider location: %v", err)
+	}
+	if location.Query().Get("state") != state || location.Query().Get("code_challenge") != pkceChallenge(verifier) || location.Query().Get("code_challenge_method") != "S256" {
+		t.Fatalf("provider location did not preserve state/PKCE: %s", location)
+	}
+	return state, verifier
+}
+
+func TestHandler_ProviderExchangeReturnsJSONAndSetsRefreshCookie(t *testing.T) {
+	router := newOAuthTestRouter(t)
+	state, verifier := beginOAuthFlow(t, router)
+	request := httptest.NewRequest(http.MethodPost, "/auth/fake/exchange", strings.NewReader(
+		"{\"code\":\"code\",\"state\":\""+state+"\",\"code_verifier\":\""+verifier+"\"}",
+	))
+	request.Header.Set("Content-Type", "application/json")
+	response := httptest.NewRecorder()
+	router.ServeHTTP(response, request)
+
+	if response.Code != http.StatusOK {
+		t.Fatalf("exchange status = %d, want 200; body=%s", response.Code, response.Body.String())
+	}
+	if response.Header().Get("Location") != "" {
+		t.Fatalf("exchange must not redirect: %q", response.Header().Get("Location"))
+	}
+	if response.Header().Get("Cache-Control") != "no-store" || response.Header().Get("Pragma") != "no-cache" {
+		t.Fatalf("token response must disable caching: Cache-Control=%q Pragma=%q", response.Header().Get("Cache-Control"), response.Header().Get("Pragma"))
+	}
+	var refreshCookie *http.Cookie
+	for _, cookie := range response.Result().Cookies() {
+		if cookie.Name == refreshCookieName && cookie.Value != "" {
+			refreshCookie = cookie
+			break
+		}
+	}
+	if refreshCookie == nil || !refreshCookie.HttpOnly || !refreshCookie.Secure || refreshCookie.Path != "/" {
+		t.Fatalf("expected secure HttpOnly refresh cookie, got %#v", refreshCookie)
+	}
+	if !strings.Contains(response.Body.String(), "\"access_token\"") || strings.Contains(response.Body.String(), "\"refresh_token\"") {
+		t.Fatalf("response must expose only the access token, got %s", response.Body.String())
+	}
+}
+
+func TestHandler_ProviderCallbackIsFrontendOwnedAndErrorsDoNotRedirect(t *testing.T) {
+	router := newOAuthTestRouter(t)
+	callback := httptest.NewRequest(http.MethodGet, "/auth/fake/callback?error=access_denied&error_description=do-not-leak", nil)
+	callbackResponse := httptest.NewRecorder()
+	router.ServeHTTP(callbackResponse, callback)
+	if callbackResponse.Code != http.StatusNotFound {
+		t.Fatalf("API callback status = %d, want 404 for frontend-owned callback", callbackResponse.Code)
+	}
+
+	invalid := httptest.NewRequest(http.MethodPost, "/auth/fake/exchange?return_to=https%3A%2F%2Fevil.example", strings.NewReader(
+		"{\"code\":\"code\",\"state\":\"\",\"code_verifier\":\""+handlerOAuthVerifier+"\",\"error_description\":\"do-not-leak\"}",
+	))
+	invalid.Header.Set("Content-Type", "application/json")
+	invalidResponse := httptest.NewRecorder()
+	router.ServeHTTP(invalidResponse, invalid)
+	if invalidResponse.Code != http.StatusBadRequest || !strings.Contains(invalidResponse.Body.String(), "oauth_state_invalid") {
+		t.Fatalf("invalid exchange response = %d %s", invalidResponse.Code, invalidResponse.Body.String())
+	}
+	if invalidResponse.Header().Get("Location") != "" || strings.Contains(invalidResponse.Body.String(), "do-not-leak") || strings.Contains(invalidResponse.Body.String(), "evil.example") {
+		t.Fatalf("exchange exposed redirect or provider details: headers=%v body=%s", invalidResponse.Header(), invalidResponse.Body.String())
+	}
+}
+
+func TestHandler_ProviderLoginAndExchangeUnconfiguredProviderUseControlledJSON(t *testing.T) {
+	router := newOAuthTestRouter(t)
+	login := httptest.NewRequest(http.MethodGet, "/auth/google/login?"+url.Values{
+		"state":                 {"client-state"},
+		"code_challenge":        {"client-code-challenge"},
+		"code_challenge_method": {"S256"},
+	}.Encode(), nil)
+	loginResponse := httptest.NewRecorder()
+	router.ServeHTTP(loginResponse, login)
+	if loginResponse.Code != http.StatusServiceUnavailable || !strings.Contains(loginResponse.Body.String(), "oauth_provider_unavailable") {
+		t.Fatalf("unconfigured provider login = %d %s", loginResponse.Code, loginResponse.Body.String())
+	}
+	if loginResponse.Header().Get("Location") != "" {
+		t.Fatalf("unconfigured provider must not redirect: %q", loginResponse.Header().Get("Location"))
+	}
+
+	exchange := httptest.NewRequest(http.MethodPost, "/auth/google/exchange", strings.NewReader(
+		"{\"code\":\"code\",\"state\":\"state\",\"code_verifier\":\"verifier\"}",
+	))
+	exchange.Header.Set("Content-Type", "application/json")
+	exchangeResponse := httptest.NewRecorder()
+	router.ServeHTTP(exchangeResponse, exchange)
+	if exchangeResponse.Code != http.StatusServiceUnavailable || !strings.Contains(exchangeResponse.Body.String(), "oauth_provider_unavailable") {
+		t.Fatalf("unconfigured provider exchange = %d %s", exchangeResponse.Code, exchangeResponse.Body.String())
+	}
+	if exchangeResponse.Header().Get("Location") != "" {
+		t.Fatalf("unconfigured provider exchange must not redirect: %q", exchangeResponse.Header().Get("Location"))
+	}
+}
+
+func TestHandler_ProviderExchangeRejectsMissingStatePKCEAndCode(t *testing.T) {
+	router := newOAuthTestRouter(t)
+	tests := []struct {
+		name string
+		body string
+		code string
+	}{
+		{name: "malformed JSON", body: "{", code: "oauth_failed"},
+		{name: "missing state", body: "{\"code\":\"code\",\"code_verifier\":\"" + handlerOAuthVerifier + "\"}", code: "oauth_state_invalid"},
+		{name: "missing verifier", body: "{\"code\":\"code\",\"state\":\"state\"}", code: "oauth_state_invalid"},
+		{name: "missing code", body: "{\"state\":\"state\",\"code_verifier\":\"" + handlerOAuthVerifier + "\"}", code: "oauth_failed"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			request := httptest.NewRequest(http.MethodPost, "/auth/fake/exchange", strings.NewReader(tt.body))
+			request.Header.Set("Content-Type", "application/json")
+			response := httptest.NewRecorder()
+			router.ServeHTTP(response, request)
+			if response.Code != http.StatusBadRequest || !strings.Contains(response.Body.String(), tt.code) {
+				t.Fatalf("exchange response = %d %s, want %s", response.Code, response.Body.String(), tt.code)
+			}
+			if response.Header().Get("Location") != "" {
+				t.Fatalf("exchange must not redirect: %q", response.Header().Get("Location"))
+			}
+		})
+	}
+}
+
+func TestHandler_ValidateBrowserCookiePolicy(t *testing.T) {
+	tests := []struct {
+		name       string
+		topology   string
+		sameSite   string
+		secure     bool
+		production bool
+		wantErr    bool
+	}{
+		{name: "same-site default", topology: "same-site", sameSite: "strict", secure: false},
+		{name: "same-origin strict", topology: "same-origin", sameSite: "strict", secure: true},
+		{name: "same-site production without secure", topology: "same-site", sameSite: "strict", secure: false, production: true, wantErr: true},
+		{name: "same-origin production secure", topology: "same-origin", sameSite: "strict", secure: true, production: true},
+		{name: "cross-site secure none", topology: "cross-site", sameSite: "none", secure: true, production: true},
+		{name: "cross-site without secure", topology: "cross-site", sameSite: "none", secure: false, wantErr: true},
+		{name: "cross-site lax", topology: "cross-site", sameSite: "lax", secure: true, wantErr: true},
+		{name: "unknown topology", topology: "mobile", sameSite: "strict", secure: true, wantErr: true},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			err := ValidateBrowserCookiePolicy(tt.topology, tt.sameSite, tt.secure, tt.production)
+			if (err != nil) != tt.wantErr {
+				t.Fatalf("validateBrowserCookiePolicy() error = %v, wantErr %v", err, tt.wantErr)
+			}
+		})
+	}
+}
+
+func TestHandler_SetRefreshCookie_CrossSiteUsesNoneAndSecure(t *testing.T) {
+	h := &Handler{refreshTTL: time.Hour, cookieSecure: true, cookieSameSite: "none"}
+	response := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(response)
+	h.setRefreshCookie(c, "refresh-token")
+
+	cookies := response.Result().Cookies()
+	if len(cookies) != 1 || cookies[0].Name != refreshCookieName || cookies[0].SameSite != http.SameSiteNoneMode || !cookies[0].Secure || !cookies[0].HttpOnly {
+		t.Fatalf("expected a cross-site None + Secure HttpOnly refresh cookie, got %#v", cookies)
+	}
+}
+
+func TestHandler_CrossSiteStateChangingRequestsRequireAnAllowedOrigin(t *testing.T) {
+	router := newCrossSiteTestRouter(t)
+	tests := []struct {
+		name       string
+		origin     string
+		wantStatus int
+	}{
+		{name: "missing origin", wantStatus: http.StatusForbidden},
+		{name: "untrusted origin", origin: "https://evil.example.test", wantStatus: http.StatusForbidden},
+		{name: "allowed exact origin", origin: "https://app.example.test", wantStatus: http.StatusNoContent},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			request := httptest.NewRequest(http.MethodPost, "/auth/logout", nil)
+			if tt.origin != "" {
+				request.Header.Set("Origin", tt.origin)
+			}
+			response := httptest.NewRecorder()
+			router.ServeHTTP(response, request)
+			if response.Code != tt.wantStatus {
+				t.Fatalf("logout status = %d, want %d; body=%s", response.Code, tt.wantStatus, response.Body.String())
+			}
+			if tt.wantStatus == http.StatusForbidden && !strings.Contains(response.Body.String(), "CSRF_ORIGIN_INVALID") {
+				t.Fatalf("missing controlled CSRF error: %s", response.Body.String())
+			}
+		})
+	}
+}
+
+func TestHandler_SetNoStoreHeaders(t *testing.T) {
+	response := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(response)
+	setNoStoreHeaders(c)
+	if response.Header().Get("Cache-Control") != "no-store" || response.Header().Get("Pragma") != "no-cache" {
+		t.Fatalf("unexpected no-store headers: %v", response.Header())
+	}
+}

package/templates/add/auth/internal/app/user/adapters/inbound/http/handler_user.go.hbs

@@ -0,0 +1,41 @@
+package httpadapter
+
+import (
+	"net/http"
+
+	"{{goModule}}/internal/shared/middleware"
+
+	"github.com/gin-gonic/gin"
+	"github.com/google/uuid"
+)
+
+func (h *Handler) resendVerification(c *gin.Context) {
+	userID := c.MustGet(middleware.UserIDKey).(uuid.UUID)
+	if err := h.svc.ResendVerificationEmail(c.Request.Context(), userID); err != nil {
+		c.Error(toHTTPError(err))
+		return
+	}
+	c.Status(http.StatusNoContent)
+}
+
+// logoutAll ends every session for the caller, including the cookie used by
+// this request.
+func (h *Handler) logoutAll(c *gin.Context) {
+	userID := c.MustGet(middleware.UserIDKey).(uuid.UUID)
+	if err := h.svc.LogoutAll(c.Request.Context(), userID); err != nil {
+		c.Error(toHTTPError(err))
+		return
+	}
+	h.clearRefreshCookie(c)
+	c.Status(http.StatusNoContent)
+}
+
+func (h *Handler) me(c *gin.Context) {
+	userID := c.MustGet(middleware.UserIDKey).(uuid.UUID)
+	u, err := h.svc.Get(c.Request.Context(), userID)
+	if err != nil {
+		c.Error(toHTTPError(err))
+		return
+	}
+	c.JSON(http.StatusOK, toMeResponse(u))
+}

package/templates/add/auth/internal/app/user/adapters/inbound/http/session_cookie.go.hbs

@@ -0,0 +1,35 @@
+package httpadapter
+
+import (
+	"net/http"
+
+	"{{goModule}}/internal/app/user/application"
+
+	"github.com/gin-gonic/gin"
+)
+
+func (h *Handler) setRefreshCookie(c *gin.Context, token string) {
+	c.SetSameSite(sameSiteFrom(h.cookieSameSite))
+	c.SetCookie(refreshCookieName, token, int(h.refreshTTL.Seconds()), "/", "", h.cookieSecure, true)
+}
+
+func (h *Handler) clearRefreshCookie(c *gin.Context) {
+	c.SetSameSite(sameSiteFrom(h.cookieSameSite))
+	c.SetCookie(refreshCookieName, "", -1, "/", "", h.cookieSecure, true)
+}
+
+// Token responses must not be retained by browsers, shared caches, or
+// intermediary middleware.
+func setNoStoreHeaders(c *gin.Context) {
+	c.Header("Cache-Control", "no-store")
+	c.Header("Pragma", "no-cache")
+}
+
+func (h *Handler) writeAuthResult(c *gin.Context, status int, result *application.AuthResult) {
+	if result.MFAChallenge != "" {
+		c.JSON(http.StatusOK, mfaChallengeResponse{MFARequired: true, Challenge: result.MFAChallenge})
+		return
+	}
+	h.setRefreshCookie(c, result.RefreshToken)
+	c.JSON(status, toCookieResponse(result.AuthResponse))
+}

package/templates/add/auth/internal/app/user/adapters/outbound/password/bcrypt.go.hbs

@@ -0,0 +1,35 @@
+package password
+
+import (
+	userports "{{goModule}}/internal/app/user/ports"
+
+	"golang.org/x/crypto/bcrypt"
+)
+
+// BCryptHasher is the production password adapter. Keeping bcrypt here means
+// register, login, reset, and seed all share one algorithm boundary.
+type BCryptHasher struct {
+	cost int
+}
+
+func NewBCryptHasher() *BCryptHasher {
+	return &BCryptHasher{cost: bcrypt.DefaultCost}
+}
+
+func (h *BCryptHasher) Hash(password string) (string, error) {
+	cost := h.cost
+	if cost <= 0 {
+		cost = bcrypt.DefaultCost
+	}
+	hash, err := bcrypt.GenerateFromPassword([]byte(password), cost)
+	if err != nil {
+		return "", err
+	}
+	return string(hash), nil
+}
+
+func (*BCryptHasher) Compare(hash, password string) error {
+	return bcrypt.CompareHashAndPassword([]byte(hash), []byte(password))
+}
+
+var _ userports.PasswordHasher = (*BCryptHasher)(nil)

package/templates/add/auth/internal/app/user/adapters/outbound/password/bcrypt_test.go.hbs

@@ -0,0 +1,20 @@
+package password
+
+import "testing"
+
+func TestBCryptHasherRoundTrip(t *testing.T) {
+	hasher := NewBCryptHasher()
+	hash, err := hasher.Hash("correct horse battery staple")
+	if err != nil {
+		t.Fatalf("hash password: %v", err)
+	}
+	if hash == "" {
+		t.Fatal("expected a password hash")
+	}
+	if err := hasher.Compare(hash, "correct horse battery staple"); err != nil {
+		t.Fatalf("compare matching password: %v", err)
+	}
+	if err := hasher.Compare(hash, "wrong password"); err == nil {
+		t.Fatal("expected a mismatched password to be rejected")
+	}
+}

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

@@ -0,0 +1,129 @@
+package postgres
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"fmt"
+	"time"
+
+	"{{goModule}}/internal/app/user/ports"
+	"{{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
+}
+
+var _ ports.MFAStore = (*PostgresMFAStore)(nil)
+
+func NewPostgresMFAStore(db *gorm.DB) *PostgresMFAStore { return &PostgresMFAStore{db: db} }
+
+func (s *PostgresMFAStore) GetEnrollment(ctx context.Context, userID uuid.UUID) (ports.MFAEnrollment, bool, error) {
+	var row MFAEnrollment
+	err := tx.From(ctx, s.db).WithContext(ctx).First(&row, "user_id = ?", userID).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return ports.MFAEnrollment{}, false, nil
+	}
+	if err != nil {
+		return ports.MFAEnrollment{}, false, err
+	}
+	return ports.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 := 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 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(&MFARecoveryCode{}).Error; err != nil {
+			return err
+		}
+		rows := make([]MFARecoveryCode, len(recoveryCodeHashes))
+		for i, hash := range recoveryCodeHashes {
+			rows[i] = 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(&MFARecoveryCode{}).Error; err != nil {
+			return err
+		}
+		return db.Where("user_id = ?", userID).Delete(&MFAEnrollment{}).Error
+	})
+}
+
+func (s *PostgresMFAStore) CreateChallenge(ctx context.Context, hash string, challenge ports.MFAChallenge) error {
+	if hash == "" || challenge.UserID == uuid.Nil || !challenge.ExpiresAt.After(time.Now()) {
+		return fmt.Errorf("MFA challenge is invalid")
+	}
+	row := 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) (ports.MFAChallenge, bool, error) {
+	var challenge ports.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 ports.MFAChallenge{}, false, nil
+	}
+	if err != nil {
+		return ports.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
+}