@nakedev/go-scaffold 0.3.3 → 0.4.3

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

@@ -0,0 +1,33 @@
+package user
+
+import (
+	"net/http"
+
+	"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 *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/sessions.go.hbs

@@ -0,0 +1,99 @@
+package user
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"{{goModule}}/internal/app/user/model"
+	"{{goModule}}/internal/shared/apperror"
+
+	"github.com/google/uuid"
+)
+
+// Refresh rotates a refresh token. A replayed, already-used token revokes
+// every session for that user; an intentionally logged-out token is rejected
+// without triggering reuse detection.
+func (s *Service) Refresh(ctx context.Context, rawRefreshToken string) (*authResponse, error) {
+	hash := hashToken(rawRefreshToken)
+	token, ok, err := s.refreshTokens.ConsumeRefreshToken(ctx, hash)
+	if err != nil {
+		return nil, apperror.NewInternal(fmt.Errorf("consume refresh token: %w", err))
+	}
+	if !ok {
+		reusedBy, used, reuseErr := s.refreshTokens.IsRefreshTokenUsed(ctx, hash)
+		if reuseErr != nil {
+			return nil, apperror.NewInternal(fmt.Errorf("check refresh token reuse: %w", reuseErr))
+		}
+		if used {
+			if revokeErr := s.refreshTokens.RevokeAllRefreshTokens(ctx, reusedBy); revokeErr != nil {
+				return nil, apperror.NewInternal(fmt.Errorf("revoke sessions after refresh token reuse: %w", revokeErr))
+			}
+		}
+		return nil, errInvalidToken()
+	}
+
+	u, err := s.repo.FindByID(ctx, token.UserID)
+	if err != nil {
+		return nil, errInvalidToken()
+	}
+	return s.issueTokens(ctx, u, token.AbsoluteExpiresAt)
+}
+
+// Logout is intentional, not reuse: a missing or already-gone token still
+// succeeds and leaves no tombstone.
+func (s *Service) Logout(ctx context.Context, rawRefreshToken string) error {
+	if rawRefreshToken == "" {
+		return nil
+	}
+	hash := hashToken(rawRefreshToken)
+	userID, ok, err := s.refreshTokens.GetRefreshToken(ctx, hash)
+	if err != nil || !ok {
+		return nil
+	}
+	return s.refreshTokens.DeleteRefreshToken(ctx, hash, userID)
+}
+
+// LogoutAll ends every refresh session for the authenticated user.
+func (s *Service) LogoutAll(ctx context.Context, userID uuid.UUID) error {
+	return s.refreshTokens.RevokeAllRefreshTokens(ctx, userID)
+}
+
+func (s *Service) issueTokens(ctx context.Context, u *model.User, absoluteExpiresAt ...time.Time) (*authResponse, error) {
+	access, err := s.issueAccessToken(
+		u.ID,
+		// go-scaffold:issue-access-token-args
+	)
+	if err != nil {
+		return nil, apperror.NewInternal(err)
+	}
+	refresh, err := randomToken()
+	if err != nil {
+		return nil, apperror.NewInternal(err)
+	}
+	clock := s.now
+	if clock == nil {
+		clock = time.Now
+	}
+	now := clock()
+	abs := now.Add(s.config.JWTRefreshMaxTTL)
+	if len(absoluteExpiresAt) > 0 && !absoluteExpiresAt[0].IsZero() {
+		abs = absoluteExpiresAt[0]
+	}
+	expiresAt := now.Add(s.config.JWTRefreshTTL)
+	if abs.Before(expiresAt) {
+		expiresAt = abs
+	}
+	if !expiresAt.After(now) || !abs.After(now) {
+		return nil, apperror.NewInternal(fmt.Errorf("refresh token lifetime is exhausted"))
+	}
+	if err := s.refreshTokens.SetRefreshToken(ctx, hashToken(refresh), refreshTokenRecord{UserID: u.ID, ExpiresAt: expiresAt, AbsoluteExpiresAt: abs}); err != nil {
+		return nil, apperror.NewInternal(err)
+	}
+	return &authResponse{
+		AccessToken:  access,
+		RefreshToken: refresh,
+		TokenType:    "Bearer",
+		ExpiresIn:    int(s.config.JWTAccessTTL.Seconds()),
+	}, nil
+}

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

@@ -4,27 +4,55 @@ import (
 	"context"
 	"time"
 
+	"{{goModule}}/internal/app/user/application"
+
 	"github.com/google/uuid"
 )
 
-// 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
+// refreshTokenStore is the session surface needed by the refresh/logout use
+// cases. Keeping this port narrow means a store for OAuth state or recovery
+// tokens cannot accidentally become a dependency of session logic.
+type RefreshTokenStore interface {
+	SetRefreshToken(ctx context.Context, tokenHash string, token refreshTokenRecord) error
 	GetRefreshToken(ctx context.Context, tokenHash string) (uuid.UUID, bool, error)
+	ConsumeRefreshToken(ctx context.Context, tokenHash string) (refreshTokenRecord, bool, error)
 	DeleteRefreshToken(ctx context.Context, tokenHash string, userID uuid.UUID) error
 	RevokeAllRefreshTokens(ctx context.Context, userID uuid.UUID) error
-	MarkRefreshTokenUsed(ctx context.Context, tokenHash string, userID uuid.UUID, ttl time.Duration) error
 	IsRefreshTokenUsed(ctx context.Context, tokenHash string) (uuid.UUID, bool, error)
+}
+
+// oauthTransactionStore is the one-time authorization attempt surface. It is
+// intentionally separate from refresh sessions: the two have different TTL,
+// replay, and operational characteristics.
+type OAuthTransactionStore interface {
+	SetLoginTransaction(ctx context.Context, stateHash string, transaction loginTransaction) error
+	ConsumeLoginTransaction(ctx context.Context, stateHash string) (loginTransaction, bool, error)
+}
+
+// recoveryTokenPort is the durable one-time-token surface. Recovery owns the
+// transaction boundary that consumes a token and updates the user, while the
+// outer service also needs the two write methods to issue links.
+type RecoveryTokenStore interface {
+	application.RecoveryTokens
 	SetPasswordResetToken(ctx context.Context, tokenHash string, userID uuid.UUID, ttl time.Duration) error
-	ConsumePasswordResetToken(ctx context.Context, tokenHash string) (uuid.UUID, bool, error)
 	SetEmailVerifyToken(ctx context.Context, tokenHash string, userID uuid.UUID, ttl time.Duration) error
-	ConsumeEmailVerifyToken(ctx context.Context, tokenHash string) (uuid.UUID, bool, error)
+}
+
+// refreshTokenRecord carries both the sliding inactivity expiry and the fixed
+// absolute expiry. A rotation may move ExpiresAt forward, but it must never
+// move AbsoluteExpiresAt forward.
+type refreshTokenRecord struct {
+	UserID            uuid.UUID `json:"user_id"`
+	ExpiresAt         time.Time `json:"expires_at"`
+	AbsoluteExpiresAt time.Time `json:"absolute_expires_at"`
+}
+
+// loginTransaction is the server-owned binding for a browser authorization
+// attempt. State itself is only hashed before storage; the provider receives
+// the original value so the frontend callback can compare it unchanged.
+type loginTransaction struct {
+	Provider      string
+	CodeChallenge string
+	Nonce         string
+	ExpiresAt     time.Time
 }

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

@@ -12,6 +12,8 @@ import (
 	"context"
 	"database/sql"
 	"errors"
+	"fmt"
+	"strings"
 	"time"
 
 	"{{goModule}}/internal/app/user/model"
@@ -24,25 +26,16 @@ import (
 const (
 	kindRefresh     = "refresh"
 	kindRefreshUsed = "refresh_used"
-	kindPasswordSet = "pwreset"
-	kindEmailVerify = "emailverify"
+	kindOAuthState  = "oauth_state"
 )
 
 type pgTokenStore struct {
-	db *gorm.DB
+	db       *gorm.DB
+	recovery *recoveryTokenStore
 }
 
-func NewPgTokenStore(db *gorm.DB) *pgTokenStore { return &pgTokenStore{db: db} }
-
-// put writes a token row, replacing any row that already carries the same
-// hash — a collision is astronomically unlikely, but "upsert" is the right
-// semantic for "this hash now means this" either way.
-func (s *pgTokenStore) put(ctx context.Context, hash, kind string, userID uuid.UUID, ttl time.Duration) error {
-	row := model.AuthToken{TokenHash: hash, UserID: userID, Kind: kind, ExpiresAt: time.Now().Add(ttl)}
-	return tx.From(ctx, s.db).WithContext(ctx).
-		Where("token_hash = ?", hash).
-		Assign(map[string]any{"user_id": userID, "kind": kind, "expires_at": row.ExpiresAt}).
-		FirstOrCreate(&row).Error
+func NewPgTokenStore(db *gorm.DB) *pgTokenStore {
+	return &pgTokenStore{db: db, recovery: newRecoveryTokenStore(db)}
 }
 
 // lookup finds a live token of the given kind. Expiry is enforced here rather
@@ -61,32 +54,59 @@ func (s *pgTokenStore) lookup(ctx context.Context, hash, kind string) (uuid.UUID
 	return row.UserID, true, nil
 }
 
-// consume deletes and returns in one statement, which is what makes a
-// one-time token actually one-time: two requests racing on the same token
-// cannot both come away with a user id.
-func (s *pgTokenStore) consume(ctx context.Context, hash, kind string) (uuid.UUID, bool, error) {
-	var userID uuid.UUID
-	err := tx.From(ctx, s.db).WithContext(ctx).Raw(
-		`DELETE FROM user_svc.auth_tokens
-		 WHERE token_hash = ? AND kind = ? AND expires_at > now()
-		 RETURNING user_id`, hash, kind).Row().Scan(&userID)
-	if errors.Is(err, sql.ErrNoRows) {
-		return uuid.Nil, false, nil
+func (s *pgTokenStore) SetRefreshToken(ctx context.Context, tokenHash string, token refreshTokenRecord) error {
+	if token.UserID == uuid.Nil || token.ExpiresAt.IsZero() || token.AbsoluteExpiresAt.IsZero() || token.AbsoluteExpiresAt.Before(token.ExpiresAt) {
+		return fmt.Errorf("refresh token record expiry is invalid")
 	}
-	if err != nil {
-		return uuid.Nil, false, err
+	row := model.AuthToken{
+		TokenHash:         tokenHash,
+		UserID:            token.UserID,
+		Kind:              kindRefresh,
+		ExpiresAt:         token.ExpiresAt,
+		AbsoluteExpiresAt: &token.AbsoluteExpiresAt,
 	}
-	return userID, true, nil
-}
-
-func (s *pgTokenStore) SetRefreshToken(ctx context.Context, tokenHash string, userID uuid.UUID, ttl time.Duration) error {
-	return s.put(ctx, tokenHash, kindRefresh, userID, ttl)
+	return tx.From(ctx, s.db).WithContext(ctx).
+		Where("token_hash = ?", tokenHash).
+		Assign(map[string]any{
+			"user_id":             token.UserID,
+			"kind":                kindRefresh,
+			"expires_at":          token.ExpiresAt,
+			"absolute_expires_at": token.AbsoluteExpiresAt,
+			"provider":            "",
+			"code_challenge":      "",
+			"nonce":               "",
+		}).FirstOrCreate(&row).Error
 }
 
 func (s *pgTokenStore) GetRefreshToken(ctx context.Context, tokenHash string) (uuid.UUID, bool, error) {
 	return s.lookup(ctx, tokenHash, kindRefresh)
 }
 
+// ConsumeRefreshToken removes the active row and writes the reuse-detection
+// tombstone in one statement. A concurrent caller can observe either the
+// active row or the tombstone, never the gap between separate operations.
+func (s *pgTokenStore) ConsumeRefreshToken(ctx context.Context, tokenHash string) (refreshTokenRecord, bool, error) {
+	var token refreshTokenRecord
+	err := tx.From(ctx, s.db).WithContext(ctx).Raw(
+		`WITH consumed AS (
+			DELETE FROM user_svc.auth_tokens
+				 WHERE token_hash = ? AND kind = ? AND expires_at > now()
+				   AND (absolute_expires_at IS NULL OR absolute_expires_at > now())
+				 RETURNING user_id, expires_at, absolute_expires_at
+		)
+		INSERT INTO user_svc.auth_tokens (token_hash, user_id, kind, expires_at, absolute_expires_at)
+		SELECT ?, user_id, ?, expires_at, COALESCE(absolute_expires_at, expires_at) FROM consumed
+		RETURNING user_id, expires_at, absolute_expires_at`,
+		tokenHash, kindRefresh, tokenHash, kindRefreshUsed).Row().Scan(&token.UserID, &token.ExpiresAt, &token.AbsoluteExpiresAt)
+	if errors.Is(err, sql.ErrNoRows) {
+		return refreshTokenRecord{}, false, nil
+	}
+	if err != nil {
+		return refreshTokenRecord{}, false, err
+	}
+	return token, true, nil
+}
+
 // DeleteRefreshToken removes the row outright and leaves nothing behind — see
 // the AuthToken doc comment for why logout must not leave a tombstone.
 func (s *pgTokenStore) DeleteRefreshToken(ctx context.Context, tokenHash string, _ uuid.UUID) error {
@@ -105,28 +125,73 @@ func (s *pgTokenStore) RevokeAllRefreshTokens(ctx context.Context, userID uuid.U
 		Delete(&model.AuthToken{}).Error
 }
 
-func (s *pgTokenStore) MarkRefreshTokenUsed(ctx context.Context, tokenHash string, userID uuid.UUID, ttl time.Duration) error {
-	return s.put(ctx, tokenHash, kindRefreshUsed, userID, ttl)
-}
-
 func (s *pgTokenStore) IsRefreshTokenUsed(ctx context.Context, tokenHash string) (uuid.UUID, bool, error) {
 	return s.lookup(ctx, tokenHash, kindRefreshUsed)
 }
 
+func (s *pgTokenStore) SetLoginTransaction(ctx context.Context, stateHash string, transaction loginTransaction) error {
+	if strings.TrimSpace(stateHash) == "" || strings.TrimSpace(transaction.Provider) == "" || strings.TrimSpace(transaction.CodeChallenge) == "" || strings.TrimSpace(transaction.Nonce) == "" || !transaction.ExpiresAt.After(time.Now()) {
+		return fmt.Errorf("oauth login transaction is invalid")
+	}
+	row := model.AuthToken{
+		TokenHash:     stateHash,
+		Kind:          kindOAuthState,
+		ExpiresAt:     transaction.ExpiresAt,
+		Provider:      transaction.Provider,
+		CodeChallenge: transaction.CodeChallenge,
+		Nonce:         transaction.Nonce,
+	}
+	return tx.From(ctx, s.db).WithContext(ctx).
+		Where("token_hash = ?", stateHash).
+		Assign(map[string]any{
+			"user_id":        uuid.Nil,
+			"kind":           kindOAuthState,
+			"expires_at":     transaction.ExpiresAt,
+			"provider":       transaction.Provider,
+			"code_challenge": transaction.CodeChallenge,
+			"nonce":          transaction.Nonce,
+		}).FirstOrCreate(&row).Error
+}
+
+func (s *pgTokenStore) ConsumeLoginTransaction(ctx context.Context, stateHash string) (loginTransaction, bool, error) {
+	var transaction loginTransaction
+	err := tx.From(ctx, s.db).WithContext(ctx).Raw(
+		`DELETE FROM user_svc.auth_tokens
+		 WHERE token_hash = ? AND kind = ? AND expires_at > now()
+		 RETURNING provider, code_challenge, nonce, expires_at`,
+		stateHash, kindOAuthState).Row().Scan(
+		&transaction.Provider,
+		&transaction.CodeChallenge,
+		&transaction.Nonce,
+		&transaction.ExpiresAt,
+	)
+	if errors.Is(err, sql.ErrNoRows) {
+		return loginTransaction{}, false, nil
+	}
+	if err != nil {
+		return loginTransaction{}, false, err
+	}
+	return transaction, true, nil
+}
+
 func (s *pgTokenStore) SetPasswordResetToken(ctx context.Context, tokenHash string, userID uuid.UUID, ttl time.Duration) error {
-	return s.put(ctx, tokenHash, kindPasswordSet, userID, ttl)
+	return s.recovery.put(ctx, tokenHash, kindPasswordSet, userID, ttl)
 }
 
 func (s *pgTokenStore) ConsumePasswordResetToken(ctx context.Context, tokenHash string) (uuid.UUID, bool, error) {
-	return s.consume(ctx, tokenHash, kindPasswordSet)
+	return s.recovery.consume(ctx, tokenHash, kindPasswordSet)
 }
 
 func (s *pgTokenStore) SetEmailVerifyToken(ctx context.Context, tokenHash string, userID uuid.UUID, ttl time.Duration) error {
-	return s.put(ctx, tokenHash, kindEmailVerify, userID, ttl)
+	return s.recovery.put(ctx, tokenHash, kindEmailVerify, userID, ttl)
 }
 
 func (s *pgTokenStore) ConsumeEmailVerifyToken(ctx context.Context, tokenHash string) (uuid.UUID, bool, error) {
-	return s.consume(ctx, tokenHash, kindEmailVerify)
+	return s.recovery.consume(ctx, tokenHash, kindEmailVerify)
+}
+
+func (s *pgTokenStore) WithTransaction(ctx context.Context, fn func(context.Context) error) error {
+	return s.recovery.withTransaction(ctx, fn)
 }
 
 // DeleteExpired drops rows nothing can use any more. Correctness never depends

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

@@ -0,0 +1,96 @@
+package user
+
+import (
+	"context"
+	"os"
+	"testing"
+
+	"github.com/google/uuid"
+	"gorm.io/driver/postgres"
+	"gorm.io/gorm"
+)
+
+// tokenStoreDBForTest opens a real database instead of reusing the repository
+// test transaction: concurrent consumers must use separate PostgreSQL
+// connections to exercise DELETE ... RETURNING's row-level serialization.
+func tokenStoreDBForTest(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("token-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 token-store database: %v", err)
+		}
+		t.Skipf("token-store integration test skipped: %v", err)
+	}
+	sqlDB, err := db.DB()
+	if err != nil {
+		t.Fatalf("get token-store SQL handle: %v", err)
+	}
+	if err := sqlDB.Ping(); err != nil {
+		if os.Getenv("REQUIRE_TEST_DB") == "true" {
+			t.Fatalf("ping required token-store database: %v", err)
+		}
+		t.Skipf("token-store integration test skipped: %v", err)
+	}
+	t.Cleanup(func() { _ = sqlDB.Close() })
+	return db
+}
+
+func TestPgTokenStore_ConsumeRefreshToken_ConcurrentRealDatabase(t *testing.T) {
+	db := tokenStoreDBForTest(t)
+	store := NewPgTokenStore(db)
+	ctx := context.Background()
+	userID := uuid.New()
+	hash := "real-pg-refresh-" + uuid.NewString()
+	if err := store.SetRefreshToken(ctx, hash, testRefreshTokenRecord(userID)); err != nil {
+		t.Fatalf("seed refresh token: %v", err)
+	}
+	t.Cleanup(func() {
+		_ = db.Exec("DELETE FROM user_svc.auth_tokens WHERE token_hash = ?", hash).Error
+	})
+
+	const callers = 32
+	type result struct {
+		token refreshTokenRecord
+		ok    bool
+		err   error
+	}
+	start := make(chan struct{})
+	results := make(chan result, callers)
+	for i := 0; i < callers; i++ {
+		go func() {
+			<-start
+			token, ok, err := store.ConsumeRefreshToken(ctx, hash)
+			results <- result{token: token, ok: ok, err: err}
+		}()
+	}
+	close(start)
+
+	winners := 0
+	for i := 0; i < callers; i++ {
+		got := <-results
+		if got.err != nil {
+			t.Fatalf("concurrent consume: %v", got.err)
+		}
+		if got.ok {
+			winners++
+			if got.token.UserID != userID {
+				t.Fatalf("winner returned user %s, want %s", got.token.UserID, userID)
+			}
+		}
+	}
+	if winners != 1 {
+		t.Fatalf("expected exactly one real-database refresh winner, got %d", winners)
+	}
+	if _, ok, err := store.GetRefreshToken(ctx, hash); err != nil || ok {
+		t.Fatalf("consumed refresh token remained active: ok=%t err=%v", ok, err)
+	}
+}

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

@@ -0,0 +1,58 @@
+package user
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"time"
+
+	"{{goModule}}/internal/app/user/model"
+	"{{goModule}}/internal/shared/tx"
+
+	"github.com/google/uuid"
+	"gorm.io/gorm"
+)
+
+const (
+	kindPasswordSet = "pwreset"
+	kindEmailVerify = "emailverify"
+)
+
+// recoveryTokenStore is deliberately Postgres-backed for both auth store
+// choices. Refresh rotation may live in Redis, but password reset and email
+// verification must share a durable DB transaction with the user update.
+type recoveryTokenStore struct {
+	db *gorm.DB
+}
+
+func newRecoveryTokenStore(db *gorm.DB) *recoveryTokenStore {
+	return &recoveryTokenStore{db: db}
+}
+
+func (s *recoveryTokenStore) withTransaction(ctx context.Context, fn func(context.Context) error) error {
+	return tx.Do(ctx, s.db, fn)
+}
+
+func (s *recoveryTokenStore) put(ctx context.Context, hash, kind string, userID uuid.UUID, ttl time.Duration) error {
+	expiresAt := time.Now().Add(ttl)
+	row := model.AuthToken{TokenHash: hash, UserID: userID, Kind: kind, ExpiresAt: expiresAt}
+	return tx.From(ctx, s.db).WithContext(ctx).
+		Where("token_hash = ?", hash).
+		Assign(map[string]any{"user_id": userID, "kind": kind, "expires_at": expiresAt}).
+		FirstOrCreate(&row).Error
+}
+
+func (s *recoveryTokenStore) consume(ctx context.Context, hash, kind string) (uuid.UUID, bool, error) {
+	var userID uuid.UUID
+	err := tx.From(ctx, s.db).WithContext(ctx).Raw(
+		`DELETE FROM user_svc.auth_tokens
+		 WHERE token_hash = ? AND kind = ? AND expires_at > now()
+		 RETURNING user_id`, hash, kind).Row().Scan(&userID)
+	if errors.Is(err, sql.ErrNoRows) {
+		return uuid.Nil, false, nil
+	}
+	if err != nil {
+		return uuid.Nil, false, err
+	}
+	return userID, true, nil
+}