@nakedev/go-scaffold 0.4.0 → 0.5.0

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

@@ -0,0 +1,213 @@
+// Postgres-backed tokenStore — installed by `add auth --store postgres` (the
+// default). The Redis-backed alternative lives in tokenstore_redis.go; only
+// one of the two is ever written into a project.
+//
+// Everything Redis needed two keys for collapses into one table here: the
+// per-user session set is just a WHERE clause, and expiry is a column every
+// read filters on rather than a TTL the store enforces. What that costs is a
+// sweep to keep the table from growing — see DeleteExpired.
+package postgres
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"fmt"
+	"strings"
+	"time"
+
+	"{{goModule}}/internal/app/user/ports"
+	"{{goModule}}/internal/shared/tx"
+
+	"github.com/google/uuid"
+	"gorm.io/gorm"
+)
+
+const (
+	kindRefresh     = "refresh"
+	kindRefreshUsed = "refresh_used"
+	kindOAuthState  = "oauth_state"
+)
+
+type PgTokenStore struct {
+	db       *gorm.DB
+	recovery *recoveryTokenStore
+}
+
+func NewPgTokenStore(db *gorm.DB) *PgTokenStore {
+	return &PgTokenStore{db: db, recovery: newRecoveryTokenStore(db)}
+}
+
+var _ ports.RefreshTokenStore = (*PgTokenStore)(nil)
+var _ ports.OAuthTransactionStore = (*PgTokenStore)(nil)
+var _ ports.RecoveryTokenStore = (*PgTokenStore)(nil)
+
+// lookup finds a live token of the given kind. Expiry is enforced here rather
+// than by a sweep, so a row that outlived its TTL is already invisible.
+func (s *PgTokenStore) lookup(ctx context.Context, hash, kind string) (uuid.UUID, bool, error) {
+	var row AuthToken
+	err := tx.From(ctx, s.db).WithContext(ctx).
+		Where("token_hash = ? AND kind = ? AND expires_at > now()", hash, kind).
+		Take(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return uuid.Nil, false, nil
+	}
+	if err != nil {
+		return uuid.Nil, false, err
+	}
+	return row.UserID, true, nil
+}
+
+func (s *PgTokenStore) SetRefreshToken(ctx context.Context, tokenHash string, token ports.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")
+	}
+	row := AuthToken{
+		TokenHash:         tokenHash,
+		UserID:            token.UserID,
+		Kind:              kindRefresh,
+		ExpiresAt:         token.ExpiresAt,
+		AbsoluteExpiresAt: &token.AbsoluteExpiresAt,
+	}
+	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) (ports.RefreshTokenRecord, bool, error) {
+	var token ports.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 ports.RefreshTokenRecord{}, false, nil
+	}
+	if err != nil {
+		return ports.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 {
+	return tx.From(ctx, s.db).WithContext(ctx).
+		Where("token_hash = ? AND kind = ?", tokenHash, kindRefresh).
+		Delete(&AuthToken{}).Error
+}
+
+// RevokeAllRefreshTokens is one statement here because Postgres can query by
+// value — the Redis store has to keep a separate per-user set to answer this,
+// and that set accumulates stale members its own comment calls out.
+// Tombstones are left in place so reuse detection still works afterwards.
+func (s *PgTokenStore) RevokeAllRefreshTokens(ctx context.Context, userID uuid.UUID) error {
+	return tx.From(ctx, s.db).WithContext(ctx).
+		Where("user_id = ? AND kind = ?", userID, kindRefresh).
+		Delete(&AuthToken{}).Error
+}
+
+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 ports.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 := 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) (ports.LoginTransaction, bool, error) {
+	var transaction ports.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 ports.LoginTransaction{}, false, nil
+	}
+	if err != nil {
+		return ports.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.recovery.put(ctx, tokenHash, kindPasswordSet, userID, ttl)
+}
+
+func (s *PgTokenStore) ConsumePasswordResetToken(ctx context.Context, tokenHash string) (uuid.UUID, bool, error) {
+	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.recovery.put(ctx, tokenHash, kindEmailVerify, userID, ttl)
+}
+
+func (s *PgTokenStore) ConsumeEmailVerifyToken(ctx context.Context, tokenHash string) (uuid.UUID, bool, error) {
+	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
+// on it — every read already filters on expires_at — so it is purely about
+// table size, and calling it on a timer from cmd/worker (or a cron) is enough.
+//
+// ponytail: not scheduled for you. Wire it up the day the table is big enough
+// to notice; a scaffold that silently runs background sweeps nobody asked for
+// is harder to reason about than one line you add when it matters.
+func (s *PgTokenStore) DeleteExpired(ctx context.Context) (int64, error) {
+	res := tx.From(ctx, s.db).WithContext(ctx).
+		Where("expires_at <= now()").
+		Delete(&AuthToken{})
+	return res.RowsAffected, res.Error
+}

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

@@ -0,0 +1,103 @@
+package postgres
+
+import (
+	"context"
+	"os"
+	"testing"
+	"time"
+
+	"{{goModule}}/internal/app/user/ports"
+	"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, refreshTokenRecordForTest(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 ports.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)
+	}
+}
+
+func refreshTokenRecordForTest(userID uuid.UUID) ports.RefreshTokenRecord {
+	now := time.Now()
+	return ports.RefreshTokenRecord{UserID: userID, ExpiresAt: now.Add(time.Hour), AbsoluteExpiresAt: now.Add(24 * time.Hour)}
+}

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

@@ -0,0 +1,84 @@
+package postgres
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"time"
+
+	"{{goModule}}/internal/app/user/ports"
+	"{{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
+}
+
+var _ ports.RecoveryTokenStore = (*recoveryTokenStore)(nil)
+
+func NewRecoveryTokenStore(db *gorm.DB) ports.RecoveryTokenStore {
+	return newRecoveryTokenStore(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 := 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
+}
+
+func (s *recoveryTokenStore) SetPasswordResetToken(ctx context.Context, tokenHash string, userID uuid.UUID, ttl time.Duration) error {
+	return s.put(ctx, tokenHash, kindPasswordSet, userID, ttl)
+}
+
+func (s *recoveryTokenStore) ConsumePasswordResetToken(ctx context.Context, tokenHash string) (uuid.UUID, bool, error) {
+	return s.consume(ctx, tokenHash, kindPasswordSet)
+}
+
+func (s *recoveryTokenStore) SetEmailVerifyToken(ctx context.Context, tokenHash string, userID uuid.UUID, ttl time.Duration) error {
+	return s.put(ctx, tokenHash, kindEmailVerify, userID, ttl)
+}
+
+func (s *recoveryTokenStore) ConsumeEmailVerifyToken(ctx context.Context, tokenHash string) (uuid.UUID, bool, error) {
+	return s.consume(ctx, tokenHash, kindEmailVerify)
+}
+
+func (s *recoveryTokenStore) WithTransaction(ctx context.Context, fn func(context.Context) error) error {
+	return s.withTransaction(ctx, fn)
+}

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

@@ -0,0 +1,228 @@
+// Redis-backed tokenStore — installed by `add auth --store redis`.
+// The Postgres-backed alternative lives in tokenstore_pg.go; only one of the
+// two is ever written into a project, and Service never learns which.
+package redisadapter
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"time"
+
+	"{{goModule}}/internal/app/user/adapters/outbound/postgres"
+	"{{goModule}}/internal/app/user/ports"
+
+	"github.com/google/uuid"
+	"github.com/redis/go-redis/v9"
+	"gorm.io/gorm"
+)
+
+const (
+	// The shared {refresh} hash tag keeps all keys touched by the Lua rotation
+	// script on one Redis Cluster slot as well as making the operation atomic.
+	refreshKeyPrefix     = "user:{refresh}:"      // +hash -> ports.RefreshTokenRecord, TTL = ExpiresAt
+	refreshUserKeyPrefix = "user:{refresh}:user:" // +userID -> SET of active token hashes
+	refreshUsedKeyPrefix = "user:{refresh}:used:" // +hash -> ports.RefreshTokenRecord, TTL = source token expiry
+	oauthStateKeyPrefix  = "user:{oauth}:state:"
+)
+
+type RedisTokenStore struct {
+	rdb      *redis.Client
+	recovery ports.RecoveryTokenStore
+}
+
+func NewRedisTokenStore(rdb *redis.Client, db *gorm.DB) *RedisTokenStore {
+	return &RedisTokenStore{rdb: rdb, recovery: postgres.NewRecoveryTokenStore(db)}
+}
+
+var _ ports.RefreshTokenStore = (*RedisTokenStore)(nil)
+var _ ports.OAuthTransactionStore = (*RedisTokenStore)(nil)
+var _ ports.RecoveryTokenStore = (*RedisTokenStore)(nil)
+
+var consumeRefreshScript = redis.NewScript(`
+local token = redis.call("GET", KEYS[1])
+local ttl = redis.call("PTTL", KEYS[1])
+if not token or ttl < 1 then
+	-- An empty bulk string maps to a normal "not found" result in go-redis;
+	-- Lua false would be surfaced as redis.Nil and look like an infrastructure
+	-- failure to Service.Refresh.
+	return ""
+end
+
+-- Decode and validate the fields used by this script before mutating anything.
+-- Redis Lua does not roll back earlier writes when a later command errors; the
+-- old order could therefore delete a corrupt active token and then fail while
+-- decoding it, losing the only evidence needed to investigate or retry safely.
+local decoded, token_data = pcall(cjson.decode, token)
+if not decoded or type(token_data) ~= "table" or
+   type(token_data.user_id) ~= "string" or token_data.user_id == "" or
+   type(token_data.expires_at) ~= "string" or token_data.expires_at == "" or
+   type(token_data.absolute_expires_at) ~= "string" or token_data.absolute_expires_at == "" then
+	return redis.error_reply("invalid refresh token record")
+end
+
+redis.call("DEL", KEYS[1])
+redis.call("SREM", KEYS[3] .. token_data.user_id, ARGV[1])
+redis.call("SET", KEYS[2], token, "PX", ttl)
+return token
+`)
+
+var revokeAllRefreshScript = redis.NewScript(`
+local hashes = redis.call("SMEMBERS", KEYS[1])
+for _, hash in ipairs(hashes) do
+  redis.call("DEL", KEYS[2] .. hash)
+end
+redis.call("DEL", KEYS[1])
+return #hashes
+`)
+
+func (s *RedisTokenStore) SetRefreshToken(ctx context.Context, tokenHash string, token ports.RefreshTokenRecord) error {
+	ttl := time.Until(token.ExpiresAt)
+	if token.UserID == uuid.Nil || ttl <= 0 || token.AbsoluteExpiresAt.IsZero() || token.AbsoluteExpiresAt.Before(token.ExpiresAt) {
+		return fmt.Errorf("refresh token expiry is invalid")
+	}
+	payload, err := json.Marshal(token)
+	if err != nil {
+		return fmt.Errorf("encode refresh token record: %w", err)
+	}
+	pipe := s.rdb.TxPipeline()
+	pipe.Set(ctx, refreshKeyPrefix+tokenHash, payload, ttl)
+	pipe.SAdd(ctx, refreshUserKeyPrefix+token.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
+	}
+	token, err := decodeRefreshTokenRecord(raw)
+	if err != nil {
+		return uuid.Nil, false, fmt.Errorf("decode refresh token record: %w", err)
+	}
+	return token.UserID, true, nil
+}
+
+// ConsumeRefreshToken uses one Lua script for active-token deletion,
+// per-user-session cleanup, and the reuse tombstone. A concurrent caller
+// cannot observe the active value after another caller has won the rotation.
+func (s *RedisTokenStore) ConsumeRefreshToken(ctx context.Context, tokenHash string) (ports.RefreshTokenRecord, bool, error) {
+	result, err := consumeRefreshScript.Run(ctx, s.rdb,
+		[]string{refreshKeyPrefix + tokenHash, refreshUsedKeyPrefix + tokenHash, refreshUserKeyPrefix},
+		tokenHash,
+	).Result()
+	if err != nil {
+		return ports.RefreshTokenRecord{}, false, err
+	}
+	raw, ok := result.(string)
+	if !ok || raw == "" {
+		return ports.RefreshTokenRecord{}, false, nil
+	}
+	token, err := decodeRefreshTokenRecord(raw)
+	if err != nil {
+		return ports.RefreshTokenRecord{}, false, fmt.Errorf("decode consumed refresh token record: %w", err)
+	}
+	return token, 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 snapshots the per-user session set, deletes every
+// active refresh token, and removes the set in one Lua invocation. This is
+// important because SetRefreshToken updates two keys: a SMEMBERS followed by
+// a separate pipeline could miss a token added between those operations and
+// leave an active token with no session-set member.
+func (s *RedisTokenStore) RevokeAllRefreshTokens(ctx context.Context, userID uuid.UUID) error {
+	setKey := refreshUserKeyPrefix + userID.String()
+	_, err := revokeAllRefreshScript.Run(ctx, s.rdb,
+		[]string{setKey, refreshKeyPrefix},
+		userID.String(),
+	).Result()
+	return 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
+	}
+	token, err := decodeRefreshTokenRecord(raw)
+	if err != nil {
+		return uuid.Nil, false, fmt.Errorf("decode used refresh token record: %w", err)
+	}
+	return token.UserID, true, nil
+}
+
+func (s *RedisTokenStore) SetLoginTransaction(ctx context.Context, stateHash string, transaction ports.LoginTransaction) error {
+	if !transaction.ExpiresAt.After(time.Now()) {
+		return fmt.Errorf("oauth login transaction expiry is invalid")
+	}
+	payload, err := json.Marshal(transaction)
+	if err != nil {
+		return fmt.Errorf("encode oauth login transaction: %w", err)
+	}
+	return s.rdb.Set(ctx, oauthStateKeyPrefix+stateHash, payload, time.Until(transaction.ExpiresAt)).Err()
+}
+
+func (s *RedisTokenStore) ConsumeLoginTransaction(ctx context.Context, stateHash string) (ports.LoginTransaction, bool, error) {
+	raw, err := s.rdb.GetDel(ctx, oauthStateKeyPrefix+stateHash).Result()
+	if err == redis.Nil {
+		return ports.LoginTransaction{}, false, nil
+	}
+	if err != nil {
+		return ports.LoginTransaction{}, false, err
+	}
+	var transaction ports.LoginTransaction
+	if err := json.Unmarshal([]byte(raw), &transaction); err != nil {
+		return ports.LoginTransaction{}, false, fmt.Errorf("decode oauth login transaction: %w", err)
+	}
+	return transaction, true, nil
+}
+
+func decodeRefreshTokenRecord(raw string) (ports.RefreshTokenRecord, error) {
+	var token ports.RefreshTokenRecord
+	if err := json.Unmarshal([]byte(raw), &token); err != nil {
+		return ports.RefreshTokenRecord{}, err
+	}
+	if token.UserID == uuid.Nil || token.ExpiresAt.IsZero() || token.AbsoluteExpiresAt.IsZero() || token.AbsoluteExpiresAt.Before(token.ExpiresAt) {
+		return ports.RefreshTokenRecord{}, fmt.Errorf("refresh token record is incomplete")
+	}
+	return token, nil
+}
+
+func (s *RedisTokenStore) SetPasswordResetToken(ctx context.Context, tokenHash string, userID uuid.UUID, ttl time.Duration) error {
+	return s.recovery.SetPasswordResetToken(ctx, tokenHash, userID, ttl)
+}
+
+// ConsumePasswordResetToken is one-time-use by construction: the SQL DELETE
+// runs inside the same transaction as the user update.
+func (s *RedisTokenStore) ConsumePasswordResetToken(ctx context.Context, tokenHash string) (uuid.UUID, bool, error) {
+	return s.recovery.ConsumePasswordResetToken(ctx, tokenHash)
+}
+
+func (s *RedisTokenStore) SetEmailVerifyToken(ctx context.Context, tokenHash string, userID uuid.UUID, ttl time.Duration) error {
+	return s.recovery.SetEmailVerifyToken(ctx, tokenHash, userID, ttl)
+}
+
+// ConsumeEmailVerifyToken is one-time-use by construction, same as
+// ConsumePasswordResetToken — the SQL delete participates in the transaction.
+func (s *RedisTokenStore) ConsumeEmailVerifyToken(ctx context.Context, tokenHash string) (uuid.UUID, bool, error) {
+	return s.recovery.ConsumeEmailVerifyToken(ctx, tokenHash)
+}
+
+func (s *RedisTokenStore) WithTransaction(ctx context.Context, fn func(context.Context) error) error {
+	return s.recovery.WithTransaction(ctx, fn)
+}