@nakedev/go-scaffold 0.4.3 → 0.5.0

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

@@ -6,7 +6,7 @@
 // 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 user
+package postgres
 
 import (
 	"context"
@@ -16,7 +16,7 @@ import (
 	"strings"
 	"time"
 
-	"{{goModule}}/internal/app/user/model"
+	"{{goModule}}/internal/app/user/ports"
 	"{{goModule}}/internal/shared/tx"
 
 	"github.com/google/uuid"
@@ -29,19 +29,23 @@ const (
 	kindOAuthState  = "oauth_state"
 )
 
-type pgTokenStore struct {
+type PgTokenStore struct {
 	db       *gorm.DB
 	recovery *recoveryTokenStore
 }
 
-func NewPgTokenStore(db *gorm.DB) *pgTokenStore {
-	return &pgTokenStore{db: db, recovery: newRecoveryTokenStore(db)}
+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 model.AuthToken
+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
@@ -54,11 +58,11 @@ func (s *pgTokenStore) lookup(ctx context.Context, hash, kind string) (uuid.UUID
 	return row.UserID, true, nil
 }
 
-func (s *pgTokenStore) SetRefreshToken(ctx context.Context, tokenHash string, token refreshTokenRecord) error {
+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 := model.AuthToken{
+	row := AuthToken{
 		TokenHash:         tokenHash,
 		UserID:            token.UserID,
 		Kind:              kindRefresh,
@@ -78,15 +82,15 @@ func (s *pgTokenStore) SetRefreshToken(ctx context.Context, tokenHash string, to
 		}).FirstOrCreate(&row).Error
 }
 
-func (s *pgTokenStore) GetRefreshToken(ctx context.Context, tokenHash string) (uuid.UUID, bool, 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
+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
@@ -99,41 +103,41 @@ func (s *pgTokenStore) ConsumeRefreshToken(ctx context.Context, tokenHash string
 		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
+		return ports.RefreshTokenRecord{}, false, nil
 	}
 	if err != nil {
-		return refreshTokenRecord{}, false, err
+		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 {
+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(&model.AuthToken{}).Error
+		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 {
+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(&model.AuthToken{}).Error
+		Delete(&AuthToken{}).Error
 }
 
-func (s *pgTokenStore) IsRefreshTokenUsed(ctx context.Context, tokenHash string) (uuid.UUID, bool, 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 loginTransaction) error {
+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 := model.AuthToken{
+	row := AuthToken{
 		TokenHash:     stateHash,
 		Kind:          kindOAuthState,
 		ExpiresAt:     transaction.ExpiresAt,
@@ -153,8 +157,8 @@ func (s *pgTokenStore) SetLoginTransaction(ctx context.Context, stateHash string
 		}).FirstOrCreate(&row).Error
 }
 
-func (s *pgTokenStore) ConsumeLoginTransaction(ctx context.Context, stateHash string) (loginTransaction, bool, error) {
-	var transaction loginTransaction
+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()
@@ -166,31 +170,31 @@ func (s *pgTokenStore) ConsumeLoginTransaction(ctx context.Context, stateHash st
 		&transaction.ExpiresAt,
 	)
 	if errors.Is(err, sql.ErrNoRows) {
-		return loginTransaction{}, false, nil
+		return ports.LoginTransaction{}, false, nil
 	}
 	if err != nil {
-		return loginTransaction{}, false, err
+		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 {
+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) {
+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 {
+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) {
+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 {
+func (s *PgTokenStore) WithTransaction(ctx context.Context, fn func(context.Context) error) error {
 	return s.recovery.withTransaction(ctx, fn)
 }
 
@@ -201,9 +205,9 @@ func (s *pgTokenStore) WithTransaction(ctx context.Context, fn func(context.Cont
 // 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) {
+func (s *PgTokenStore) DeleteExpired(ctx context.Context) (int64, error) {
 	res := tx.From(ctx, s.db).WithContext(ctx).
 		Where("expires_at <= now()").
-		Delete(&model.AuthToken{})
+		Delete(&AuthToken{})
 	return res.RowsAffected, res.Error
 }

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

@@ -1,10 +1,12 @@
-package user
+package postgres
 
 import (
 	"context"
 	"os"
 	"testing"
+	"time"
 
+	"{{goModule}}/internal/app/user/ports"
 	"github.com/google/uuid"
 	"gorm.io/driver/postgres"
 	"gorm.io/gorm"
@@ -50,7 +52,7 @@ func TestPgTokenStore_ConsumeRefreshToken_ConcurrentRealDatabase(t *testing.T) {
 	ctx := context.Background()
 	userID := uuid.New()
 	hash := "real-pg-refresh-" + uuid.NewString()
-	if err := store.SetRefreshToken(ctx, hash, testRefreshTokenRecord(userID)); err != nil {
+	if err := store.SetRefreshToken(ctx, hash, refreshTokenRecordForTest(userID)); err != nil {
 		t.Fatalf("seed refresh token: %v", err)
 	}
 	t.Cleanup(func() {
@@ -59,7 +61,7 @@ func TestPgTokenStore_ConsumeRefreshToken_ConcurrentRealDatabase(t *testing.T) {
 
 	const callers = 32
 	type result struct {
-		token refreshTokenRecord
+		token ports.RefreshTokenRecord
 		ok    bool
 		err   error
 	}
@@ -94,3 +96,8 @@ func TestPgTokenStore_ConsumeRefreshToken_ConcurrentRealDatabase(t *testing.T) {
 		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/{tokenstore_recovery.go.hbs → adapters/outbound/postgres/tokenstore_recovery.go.hbs}

@@ -1,4 +1,4 @@
-package user
+package postgres
 
 import (
 	"context"
@@ -6,7 +6,7 @@ import (
 	"errors"
 	"time"
 
-	"{{goModule}}/internal/app/user/model"
+	"{{goModule}}/internal/app/user/ports"
 	"{{goModule}}/internal/shared/tx"
 
 	"github.com/google/uuid"
@@ -25,6 +25,12 @@ 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}
 }
@@ -35,7 +41,7 @@ func (s *recoveryTokenStore) withTransaction(ctx context.Context, fn func(contex
 
 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}
+	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}).
@@ -56,3 +62,23 @@ func (s *recoveryTokenStore) consume(ctx context.Context, hash, kind string) (uu
 	}
 	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/{tokenstore_redis.go.hbs → adapters/outbound/redis/tokenstore.go.hbs}

@@ -1,7 +1,7 @@
 // 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 user
+package redisadapter
 
 import (
 	"context"
@@ -9,6 +9,9 @@ import (
 	"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"
@@ -17,21 +20,25 @@ import (
 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 -> refreshTokenRecord, TTL = ExpiresAt
+	refreshKeyPrefix     = "user:{refresh}:"      // +hash -> ports.RefreshTokenRecord, TTL = ExpiresAt
 	refreshUserKeyPrefix = "user:{refresh}:user:" // +userID -> SET of active token hashes
-	refreshUsedKeyPrefix = "user:{refresh}:used:" // +hash -> refreshTokenRecord, TTL = source token expiry
+	refreshUsedKeyPrefix = "user:{refresh}:used:" // +hash -> ports.RefreshTokenRecord, TTL = source token expiry
 	oauthStateKeyPrefix  = "user:{oauth}:state:"
 )
 
-type redisTokenStore struct {
+type RedisTokenStore struct {
 	rdb      *redis.Client
-	recovery *recoveryTokenStore
+	recovery ports.RecoveryTokenStore
 }
 
-func NewRedisTokenStore(rdb *redis.Client, db *gorm.DB) *redisTokenStore {
-	return &redisTokenStore{rdb: rdb, recovery: newRecoveryTokenStore(db)}
+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])
@@ -69,7 +76,7 @@ redis.call("DEL", KEYS[1])
 return #hashes
 `)
 
-func (s *redisTokenStore) SetRefreshToken(ctx context.Context, tokenHash string, token refreshTokenRecord) error {
+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")
@@ -85,7 +92,7 @@ func (s *redisTokenStore) SetRefreshToken(ctx context.Context, tokenHash string,
 	return err
 }
 
-func (s *redisTokenStore) GetRefreshToken(ctx context.Context, tokenHash string) (uuid.UUID, bool, error) {
+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
@@ -103,26 +110,26 @@ func (s *redisTokenStore) GetRefreshToken(ctx context.Context, tokenHash string)
 // 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) (refreshTokenRecord, bool, error) {
+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 refreshTokenRecord{}, false, err
+		return ports.RefreshTokenRecord{}, false, err
 	}
 	raw, ok := result.(string)
 	if !ok || raw == "" {
-		return refreshTokenRecord{}, false, nil
+		return ports.RefreshTokenRecord{}, false, nil
 	}
 	token, err := decodeRefreshTokenRecord(raw)
 	if err != nil {
-		return refreshTokenRecord{}, false, fmt.Errorf("decode consumed refresh token record: %w", err)
+		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 {
+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)
@@ -135,7 +142,7 @@ func (s *redisTokenStore) DeleteRefreshToken(ctx context.Context, tokenHash stri
 // 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 {
+func (s *RedisTokenStore) RevokeAllRefreshTokens(ctx context.Context, userID uuid.UUID) error {
 	setKey := refreshUserKeyPrefix + userID.String()
 	_, err := revokeAllRefreshScript.Run(ctx, s.rdb,
 		[]string{setKey, refreshKeyPrefix},
@@ -144,7 +151,7 @@ func (s *redisTokenStore) RevokeAllRefreshTokens(ctx context.Context, userID uui
 	return err
 }
 
-func (s *redisTokenStore) IsRefreshTokenUsed(ctx context.Context, tokenHash string) (uuid.UUID, bool, error) {
+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
@@ -159,7 +166,7 @@ func (s *redisTokenStore) IsRefreshTokenUsed(ctx context.Context, tokenHash stri
 	return token.UserID, true, nil
 }
 
-func (s *redisTokenStore) SetLoginTransaction(ctx context.Context, stateHash string, transaction loginTransaction) error {
+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")
 	}
@@ -170,52 +177,52 @@ func (s *redisTokenStore) SetLoginTransaction(ctx context.Context, stateHash str
 	return s.rdb.Set(ctx, oauthStateKeyPrefix+stateHash, payload, time.Until(transaction.ExpiresAt)).Err()
 }
 
-func (s *redisTokenStore) ConsumeLoginTransaction(ctx context.Context, stateHash string) (loginTransaction, bool, error) {
+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 loginTransaction{}, false, nil
+		return ports.LoginTransaction{}, false, nil
 	}
 	if err != nil {
-		return loginTransaction{}, false, err
+		return ports.LoginTransaction{}, false, err
 	}
-	var transaction loginTransaction
+	var transaction ports.LoginTransaction
 	if err := json.Unmarshal([]byte(raw), &transaction); err != nil {
-		return loginTransaction{}, false, fmt.Errorf("decode oauth login transaction: %w", err)
+		return ports.LoginTransaction{}, false, fmt.Errorf("decode oauth login transaction: %w", err)
 	}
 	return transaction, true, nil
 }
 
-func decodeRefreshTokenRecord(raw string) (refreshTokenRecord, error) {
-	var token refreshTokenRecord
+func decodeRefreshTokenRecord(raw string) (ports.RefreshTokenRecord, error) {
+	var token ports.RefreshTokenRecord
 	if err := json.Unmarshal([]byte(raw), &token); err != nil {
-		return refreshTokenRecord{}, err
+		return ports.RefreshTokenRecord{}, err
 	}
 	if token.UserID == uuid.Nil || token.ExpiresAt.IsZero() || token.AbsoluteExpiresAt.IsZero() || token.AbsoluteExpiresAt.Before(token.ExpiresAt) {
-		return refreshTokenRecord{}, fmt.Errorf("refresh token record is incomplete")
+		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.put(ctx, tokenHash, kindPasswordSet, userID, ttl)
+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.consume(ctx, tokenHash, kindPasswordSet)
+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.put(ctx, tokenHash, kindEmailVerify, userID, ttl)
+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.consume(ctx, tokenHash, kindEmailVerify)
+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)
+func (s *RedisTokenStore) WithTransaction(ctx context.Context, fn func(context.Context) error) error {
+	return s.recovery.WithTransaction(ctx, fn)
 }

package/templates/add/auth/internal/app/user/{tokenstore_redis_test.go.hbs → adapters/outbound/redis/tokenstore_test.go.hbs}

@@ -1,4 +1,4 @@
-package user
+package redisadapter
 
 import (
 	"context"
@@ -8,10 +8,21 @@ import (
 	"testing"
 	"time"
 
+	"{{goModule}}/internal/app/user/ports"
+
 	"github.com/google/uuid"
 	"github.com/redis/go-redis/v9"
 )
 
+func testRefreshTokenRecord(userID uuid.UUID) ports.RefreshTokenRecord {
+	now := time.Now()
+	return ports.RefreshTokenRecord{
+		UserID:            userID,
+		ExpiresAt:         now.Add(time.Hour),
+		AbsoluteExpiresAt: now.Add(24 * time.Hour),
+	}
+}
+
 func redisClientForTest(t *testing.T) *redis.Client {
 	t.Helper()
 	url := os.Getenv("TEST_REDIS_URL")
@@ -73,7 +84,7 @@ func TestRedisTokenStore_ConsumeRefreshToken_ConcurrentRealRedis(t *testing.T) {
 	const callers = 32
 	start := make(chan struct{})
 	results := make(chan struct {
-		token refreshTokenRecord
+		token ports.RefreshTokenRecord
 		ok    bool
 		err   error
 	}, callers)
@@ -82,7 +93,7 @@ func TestRedisTokenStore_ConsumeRefreshToken_ConcurrentRealRedis(t *testing.T) {
 			<-start
 			token, ok, err := store.ConsumeRefreshToken(ctx, hash)
 			results <- struct {
-				token refreshTokenRecord
+				token ports.RefreshTokenRecord
 				ok    bool
 				err   error
 			}{token: token, ok: ok, err: err}

package/templates/add/auth/internal/app/user/application/contracts.go.hbs

@@ -0,0 +1,52 @@
+package application
+
+import (
+	"time"
+
+	"{{goModule}}/internal/app/user/ports"
+)
+
+// Dependencies is the explicit application composition contract for auth.
+// Each port represents one lifecycle or capability so an adapter does not
+// have to implement unrelated token operations.
+type Dependencies struct {
+	Repository        ports.UserRepository
+	Passwords         ports.PasswordHasher
+	RefreshTokens     ports.RefreshTokenStore
+	OAuthTransactions ports.OAuthTransactionStore
+	RecoveryTokens    ports.RecoveryTokenStore
+	MFA               ports.MFAStore
+	Mailer            ports.AuthMailer
+	Providers         ProviderRegistry
+	Roles             ports.RoleChecker
+	Clock             func() time.Time
+}
+
+type MFASettings struct {
+	Enabled           bool
+	Issuer            string
+	EncryptionKey     string
+	ChallengeTTL      time.Duration
+	TOTPWindow        int
+	RecoveryCodeCount int
+}
+
+type AuthConfig struct {
+	JWTSecret        string
+	JWTAccessTTL     time.Duration
+	JWTRefreshTTL    time.Duration
+	JWTRefreshMaxTTL time.Duration
+	OAuthStateTTL    time.Duration
+	PasswordResetTTL time.Duration
+	PasswordResetURL string
+	EmailVerifyTTL   time.Duration
+	EmailVerifyURL   string
+	MFA              MFASettings
+}
+
+// These aliases keep use-case code concise while the contracts remain owned
+// by the module's ports package. Adapters import ports directly.
+type UserRepository = ports.UserRepository
+type AuthMailer = ports.AuthMailer
+type RoleChecker = ports.RoleChecker
+type PasswordHasher = ports.PasswordHasher

package/templates/add/auth/internal/app/user/application/dto.go.hbs

@@ -0,0 +1,75 @@
+package application
+
+import (
+	"time"
+
+	"{{goModule}}/internal/app/user/domain"
+
+	"github.com/google/uuid"
+)
+
+type RegisterInput struct {
+	Email    string
+	Password string
+	Name     string
+}
+
+type LoginInput struct {
+	Email    string
+	Password string
+}
+
+type LoginExchangeInput struct {
+	Code         string
+	State        string
+	CodeVerifier string
+}
+
+type AuthResponse struct {
+	AccessToken  string
+	RefreshToken string
+	TokenType    string
+	ExpiresIn    int
+}
+
+type AuthResult struct {
+	*AuthResponse
+	MFAChallenge string
+}
+
+func TokenResult(auth *AuthResponse) *AuthResult {
+	return &AuthResult{AuthResponse: auth}
+}
+
+func ChallengeResult(challenge string) *AuthResult {
+	return &AuthResult{MFAChallenge: challenge}
+}
+
+// Response is the generic application response used by generated method
+// extensions. Auth's HTTP adapter may expose a richer meResponse, but method
+// generation still has one stable transport-neutral mapping seam.
+type Response struct {
+	ID            uuid.UUID
+	Email         string
+	Name          string
+	AvatarURL     string
+	EmailVerified bool
+	Role          string
+	CreatedAt     time.Time
+	UpdatedAt     time.Time
+}
+
+func ToResponse(user *domain.User) Response {
+	return Response{
+		ID:            user.ID,
+		Email:         user.Email,
+		Name:          user.Name,
+		AvatarURL:     user.AvatarURL,
+		EmailVerified: user.EmailVerified,
+		Role:          user.Role,
+		CreatedAt:     user.CreatedAt,
+		UpdatedAt:     user.UpdatedAt,
+	}
+}
+
+// go-scaffold:dto