@nakedev/go-scaffold 0.4.0 → 0.5.0

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

@@ -0,0 +1,99 @@
+package application
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"{{goModule}}/internal/app/user/domain"
+
+	"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, fmt.Errorf("consume refresh token: %w", err)
+	}
+	if !ok {
+		reusedBy, used, reuseErr := s.refreshTokens.IsRefreshTokenUsed(ctx, hash)
+		if reuseErr != nil {
+			return nil, fmt.Errorf("check refresh token reuse: %w", reuseErr)
+		}
+		if used {
+			if revokeErr := s.refreshTokens.RevokeAllRefreshTokens(ctx, reusedBy); revokeErr != nil {
+				return nil, 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 *domain.User, absoluteExpiresAt ...time.Time) (*AuthResponse, error) {
+	access, err := s.issueAccessToken(
+		u.ID,
+		u.Role,
+		// go-scaffold:issue-access-token-args
+	)
+	if err != nil {
+		return nil, fmt.Errorf("issue access token: %w", err)
+	}
+	refresh, err := randomToken()
+	if err != nil {
+		return nil, fmt.Errorf("generate refresh token: %w", 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, 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, fmt.Errorf("store refresh token: %w", err)
+	}
+	return &AuthResponse{
+		AccessToken:  access,
+		RefreshToken: refresh,
+		TokenType:    "Bearer",
+		ExpiresIn:    int(s.config.JWTAccessTTL.Seconds()),
+	}, nil
+}

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

@@ -0,0 +1,14 @@
+package application
+
+import "{{goModule}}/internal/app/user/ports"
+
+// These aliases keep the use-case files readable while the actual outbound
+// contracts remain owned by the user module's ports package.
+type RefreshTokenStore = ports.RefreshTokenStore
+type OAuthTransactionStore = ports.OAuthTransactionStore
+type RecoveryTokenStore = ports.RecoveryTokenStore
+type RefreshTokenRecord = ports.RefreshTokenRecord
+type LoginTransaction = ports.LoginTransaction
+type MFAEnrollment = ports.MFAEnrollment
+type MFAChallenge = ports.MFAChallenge
+type MFAStore = ports.MFAStore

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

@@ -0,0 +1,65 @@
+package application
+
+import (
+	"context"
+	"errors"
+	"fmt"
+
+	"{{goModule}}/internal/app/user/domain"
+	"{{goModule}}/internal/shared/id"
+
+	"github.com/google/uuid"
+)
+
+// wrapFindErr is shared by methods added through `generate method`. Keeping
+// not-found translation in this query file means the small service facade
+// does not need to import database-specific error packages just because a
+// later method was generated.
+func wrapFindErr(err error) error {
+	if errors.Is(err, domain.ErrNotFound) {
+		return errNotFound()
+	}
+	return fmt.Errorf("find user: %w", err)
+}
+
+func (s *Service) Get(ctx context.Context, userID uuid.UUID) (*domain.User, error) {
+	u, err := s.repo.FindByID(ctx, userID)
+	if err != nil {
+		return nil, wrapFindErr(err)
+	}
+	return u, nil
+}
+
+// List is kept for the optional RBAC admin routes. It is not part of the
+// public self-service auth surface until that feature is installed.
+func (s *Service) List(ctx context.Context, limit, offset int) ([]domain.User, error) {
+	items, err := s.repo.FindAll(ctx, limit, offset)
+	if err != nil {
+		return nil, fmt.Errorf("list users: %w", err)
+	}
+	return items, nil
+}
+
+// EnsureUser is idempotent and used only by cmd/seed. It never resets an
+// existing user's password as a side effect of a later deployment.
+func (s *Service) EnsureUser(ctx context.Context, email, password, name string) (*domain.User, error) {
+	email = normalizeEmail(email)
+	if u, err := s.repo.FindByEmail(ctx, email); err == nil {
+		return u, nil
+	} else if !errors.Is(err, domain.ErrNotFound) {
+		return nil, fmt.Errorf("find existing user: %w", err)
+	}
+
+	hash, err := s.passwords.Hash(password)
+	if err != nil {
+		return nil, fmt.Errorf("hash password: %w", err)
+	}
+	hashStr := string(hash)
+
+	u := &domain.User{ID: id.New(), Email: email, Name: name, Role: domain.DefaultRole}
+	i := &domain.Identity{ID: id.New(), Provider: domain.ProviderLocal, PasswordHash: &hashStr}
+	if err := s.repo.CreateUserWithIdentity(ctx, u, i); err != nil {
+		return nil, fmt.Errorf("create user: %w", err)
+	}
+	return u, nil
+}

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

@@ -0,0 +1,168 @@
+package user
+
+import (
+	"fmt"
+	"time"
+
+	httpadapter "{{goModule}}/internal/app/user/adapters/inbound/http"
+	userpassword "{{goModule}}/internal/app/user/adapters/outbound/password"
+	userpostgres "{{goModule}}/internal/app/user/adapters/outbound/postgres"
+	"{{goModule}}/internal/app/user/application"
+	"{{goModule}}/internal/app/user/ports"
+	googleprovider "{{goModule}}/internal/platform/authprovider/google"
+	"{{goModule}}/internal/platform/mail"
+{{#if worker}}
+	"{{goModule}}/internal/platform/queue"
+{{/if}}
+	"{{goModule}}/internal/shared/config"
+	"{{goModule}}/internal/shared/middleware"
+
+{{#if redis}}
+	userredis "{{goModule}}/internal/app/user/adapters/outbound/redis"
+	"github.com/redis/go-redis/v9"
+{{/if}}
+	"github.com/gin-gonic/gin"
+	"gorm.io/gorm"
+)
+
+// NewHandlerFromDB is the user module's composition root. It assembles the
+// application service and adapters here; cmd/api only supplies process-level
+// infrastructure and registers the returned inbound handler.
+func NewHandlerFromDB(
+	db *gorm.DB,
+	cfg config.Config,
+{{#if redis}}
+	rdb *redis.Client,
+{{/if}}
+{{#if worker}}
+	q queue.Enqueuer,
+{{/if}}
+	roleChecker RoleChecker,
+	authz Authorizer,
+) *httpadapter.Handler {
+{{#if redis}}
+	tokens := userredis.NewRedisTokenStore(rdb, db)
+{{else}}
+	tokens := userpostgres.NewPgTokenStore(db)
+{{/if}}
+
+{{#if worker}}
+	mailer := mail.NewAsyncClient(q)
+{{else}}
+	mailer := mail.NewSyncClient(mail.Open(cfg))
+{{/if}}
+
+	providers := make([]application.LoginProvider, 0, 1)
+	if cfg.GoogleClientID != "" && cfg.GoogleClientSecret != "" && cfg.GoogleOAuthRedirectURI != "" {
+		providers = append(providers, googleprovider.New(googleprovider.Config{
+			ClientID:     cfg.GoogleClientID,
+			ClientSecret: cfg.GoogleClientSecret,
+			RedirectURL:  cfg.GoogleOAuthRedirectURI,
+		}))
+	}
+	providerRegistry := application.NewProviderRegistry(providers...)
+	if err := httpadapter.ValidateBrowserCookiePolicy(cfg.AuthBrowserTopology, cfg.CookieSameSite, cfg.CookieSecure, cfg.IsProd()); err != nil {
+		panic(err)
+	}
+	if cfg.JWTRefreshTTL <= 0 || cfg.JWTRefreshMaxTTL <= 0 {
+		panic(fmt.Errorf("JWT refresh token lifetimes must be positive"))
+	}
+	if cfg.OAuthStateTTL <= 0 {
+		panic(fmt.Errorf("OAUTH_STATE_TTL_MIN must be positive"))
+	}
+
+	service := application.NewService(application.Dependencies{
+		Repository:        userpostgres.NewRepository(db),
+		Passwords:         userpassword.NewBCryptHasher(),
+		RefreshTokens:     tokens,
+		OAuthTransactions: tokens,
+		RecoveryTokens:    tokens,
+		MFA:               userpostgres.NewPostgresMFAStore(db),
+		Mailer:            mailer,
+		Providers:         providerRegistry,
+		Roles:             roleChecker,
+		Clock:             time.Now,
+	}, application.AuthConfig{
+		JWTSecret:        cfg.JWTSecret,
+		JWTAccessTTL:     cfg.JWTAccessTTL,
+		JWTRefreshTTL:    cfg.JWTRefreshTTL,
+		JWTRefreshMaxTTL: cfg.JWTRefreshMaxTTL,
+		OAuthStateTTL:    cfg.OAuthStateTTL,
+		PasswordResetTTL: cfg.PasswordResetTTL,
+		PasswordResetURL: cfg.PasswordResetURL,
+		EmailVerifyTTL:   cfg.EmailVerifyTTL,
+		EmailVerifyURL:   cfg.EmailVerifyURL,
+		MFA: application.MFASettings{
+			Enabled:           cfg.AuthMFAEnabled,
+			Issuer:            cfg.MFAIssuer,
+			EncryptionKey:     cfg.MFAEncryptionKey,
+			ChallengeTTL:      cfg.MFAChallengeTTL,
+			TOTPWindow:        cfg.MFATOTPWindow,
+			RecoveryCodeCount: cfg.MFARecoveryCodeCount,
+		},
+	})
+{{#if redis}}
+	limiter := middleware.NewRedisLimiter(rdb)
+{{else}}
+	limiter := middleware.NewMemoryLimiter()
+{{/if}}
+	return httpadapter.NewHandlerWithOrigins(
+		service,
+		cfg.JWTSecret,
+		cfg.JWTRefreshTTL,
+		cfg.CookieSecure,
+		cfg.CookieSameSite,
+		cfg.CORSAllowedOrigins,
+		limiter,
+		authz,
+	)
+}
+
+// Public aliases keep the composition surface small for cmd/seed and for
+// optional RBAC wiring. Consumers do not need to know adapter package names.
+type Dependencies = application.Dependencies
+type AuthConfig = application.AuthConfig
+type MFASettings = application.MFASettings
+type ProviderRegistry = application.ProviderRegistry
+type RoleChecker = ports.RoleChecker
+type Service = application.Service
+type ServicePort = application.ServicePort
+type Repository = userpostgres.Repository
+{{#unless redis}}
+type PgTokenStore = userpostgres.PgTokenStore
+{{/unless}}
+type PostgresMFAStore = userpostgres.PostgresMFAStore
+{{#if redis}}
+type RedisTokenStore = userredis.RedisTokenStore
+{{/if}}
+
+type Authorizer interface {
+	Require(string) gin.HandlerFunc
+}
+
+func NewService(deps Dependencies, cfg AuthConfig) *Service {
+	return application.NewService(deps, cfg)
+}
+
+func ValidateMFASettings(settings MFASettings) error {
+	return application.ValidateMFASettings(settings)
+}
+
+func NewRepository(db *gorm.DB) *Repository {
+	return userpostgres.NewRepository(db)
+}
+
+{{#unless redis}}
+func NewPgTokenStore(db *gorm.DB) *PgTokenStore {
+	return userpostgres.NewPgTokenStore(db)
+}
+{{/unless}}
+
+func NewPostgresMFAStore(db *gorm.DB) *PostgresMFAStore {
+	return userpostgres.NewPostgresMFAStore(db)
+}
+{{#if redis}}
+func NewRedisTokenStore(rdb *redis.Client, db *gorm.DB) *RedisTokenStore {
+	return userredis.NewRedisTokenStore(rdb, db)
+}
+{{/if}}

package/templates/add/auth/internal/app/user/domain/entity.go.hbs

@@ -0,0 +1,41 @@
+// Package domain contains transport- and persistence-neutral user values.
+package domain
+
+import (
+	"time"
+
+	"github.com/google/uuid"
+)
+
+type User struct {
+	ID            uuid.UUID
+	Email         string
+	Name          string
+	AvatarURL     string
+	EmailVerified bool
+	Role          string
+	CreatedAt     time.Time
+	UpdatedAt     time.Time
+}
+
+// DefaultRole is part of auth's persisted user contract. RBAC may add the
+// role catalog later, but every newly issued access token must carry the same
+// default that the users migration applies at the database boundary.
+const DefaultRole = "staff"
+
+type Provider string
+
+const (
+	ProviderLocal  Provider = "local"
+	ProviderGoogle Provider = "google"
+)
+
+type Identity struct {
+	ID           uuid.UUID
+	UserID       uuid.UUID
+	Provider     Provider
+	PasswordHash *string
+	ProviderUID  *string
+	CreatedAt    time.Time
+	UpdatedAt    time.Time
+}

package/templates/add/auth/internal/app/user/domain/errors.go.hbs

@@ -0,0 +1,32 @@
+package domain
+
+import "errors"
+
+var (
+	ErrNotFound          = errors.New("user not found")
+	ErrConflict          = errors.New("user conflict")
+	ErrInvalidCredential = errors.New("invalid credentials")
+	ErrInvalidToken      = errors.New("invalid or expired token")
+	ErrEmailTaken        = errors.New("email already registered")
+	ErrTooManyAttempts   = errors.New("too many failed attempts")
+	ErrAlreadyVerified   = errors.New("email already verified")
+	ErrMFAUnavailable    = errors.New("MFA is unavailable")
+	ErrMFAInvalid        = errors.New("invalid or expired MFA code")
+	ErrMFAAlreadyEnabled = errors.New("MFA is already enabled")
+	ErrMFANotEnrolled    = errors.New("MFA is not enrolled")
+	ErrMFASetupRequired  = errors.New("MFA setup is required")
+	ErrUnknownRole       = errors.New("unknown role")
+)
+
+type RuleError struct {
+	Code    string
+	Message string
+	Cause   error
+}
+
+func (e *RuleError) Error() string { return e.Message }
+func (e *RuleError) Unwrap() error { return e.Cause }
+
+func Rule(code, message string, cause error) error {
+	return &RuleError{Code: code, Message: message, Cause: cause}
+}

package/templates/add/auth/internal/app/user/ports/password.go.hbs

@@ -0,0 +1,9 @@
+package ports
+
+// PasswordHasher is the application-owned outbound contract for password
+// storage and verification. The algorithm and cost policy belong to an
+// adapter, not to the auth use cases.
+type PasswordHasher interface {
+	Hash(string) (string, error)
+	Compare(hash, password string) error
+}

package/templates/add/auth/internal/app/user/ports/repository.go.hbs

@@ -0,0 +1,90 @@
+// Package ports contains user auth's application-owned outbound contracts.
+package ports
+
+import (
+	"context"
+	"time"
+
+	"{{goModule}}/internal/app/user/domain"
+
+	"github.com/google/uuid"
+)
+
+type UserRepository interface {
+	FindByEmail(context.Context, string) (*domain.User, error)
+	FindByID(context.Context, uuid.UUID) (*domain.User, error)
+	UpdateUser(context.Context, *domain.User) error
+	FindAll(context.Context, int, int) ([]domain.User, error)
+	FindIdentity(context.Context, uuid.UUID, domain.Provider) (*domain.Identity, error)
+	FindIdentityByProviderUID(context.Context, domain.Provider, string) (*domain.Identity, error)
+	CreateUserWithIdentity(context.Context, *domain.User, *domain.Identity) error
+	CreateIdentity(context.Context, *domain.Identity) error
+	UpdateIdentity(context.Context, *domain.Identity) error
+	LoginLockedUntil(context.Context, string) (time.Time, error)
+	RecordLoginFailure(context.Context, string, int, time.Duration) error
+	ClearLoginFailures(context.Context, string) error
+	// go-scaffold:repository-interface
+}
+
+type AuthMailer interface {
+	Send(context.Context, string, string, string) error
+}
+
+type RoleChecker interface {
+	CodeExists(context.Context, string) (bool, error)
+}
+
+type RefreshTokenRecord struct {
+	UserID            uuid.UUID `json:"user_id"`
+	ExpiresAt         time.Time `json:"expires_at"`
+	AbsoluteExpiresAt time.Time `json:"absolute_expires_at"`
+}
+
+type RefreshTokenStore interface {
+	SetRefreshToken(context.Context, string, RefreshTokenRecord) error
+	GetRefreshToken(context.Context, string) (uuid.UUID, bool, error)
+	ConsumeRefreshToken(context.Context, string) (RefreshTokenRecord, bool, error)
+	DeleteRefreshToken(context.Context, string, uuid.UUID) error
+	RevokeAllRefreshTokens(context.Context, uuid.UUID) error
+	IsRefreshTokenUsed(context.Context, string) (uuid.UUID, bool, error)
+}
+
+type LoginTransaction struct {
+	Provider      string    `json:"provider"`
+	CodeChallenge string    `json:"code_challenge"`
+	Nonce         string    `json:"nonce"`
+	ExpiresAt     time.Time `json:"expires_at"`
+}
+
+type OAuthTransactionStore interface {
+	SetLoginTransaction(context.Context, string, LoginTransaction) error
+	ConsumeLoginTransaction(context.Context, string) (LoginTransaction, bool, error)
+}
+
+type RecoveryTokenStore interface {
+	WithTransaction(context.Context, func(context.Context) error) error
+	ConsumePasswordResetToken(context.Context, string) (uuid.UUID, bool, error)
+	ConsumeEmailVerifyToken(context.Context, string) (uuid.UUID, bool, error)
+	SetPasswordResetToken(context.Context, string, uuid.UUID, time.Duration) error
+	SetEmailVerifyToken(context.Context, string, uuid.UUID, time.Duration) error
+}
+
+type MFAEnrollment struct {
+	EncryptedSecret string
+	Enabled         bool
+}
+
+type MFAChallenge struct {
+	UserID    uuid.UUID
+	ExpiresAt time.Time
+}
+
+type MFAStore interface {
+	GetEnrollment(context.Context, uuid.UUID) (MFAEnrollment, bool, error)
+	PutPendingEnrollment(context.Context, uuid.UUID, string) error
+	ConfirmEnrollment(context.Context, uuid.UUID, string, []string) error
+	Disable(context.Context, uuid.UUID) error
+	CreateChallenge(context.Context, string, MFAChallenge) error
+	ConsumeChallenge(context.Context, string) (MFAChallenge, bool, error)
+	ConsumeRecoveryCode(context.Context, uuid.UUID, string) (bool, error)
+}