@nakedev/go-scaffold 0.4.3 → 0.5.0

package/templates/add/auth/internal/app/user/{provider_test.go.hbs → application/provider_test.go.hbs}

@@ -1,4 +1,4 @@
-package user
+package application
 
 import (
 	"context"
@@ -7,39 +7,38 @@ import (
 	"strings"
 	"testing"
 	"time"
-
-	"{{goModule}}/internal/app/user/application"
 )
 
 type fakeLoginProvider struct {
 	name        string
-	beginFn     func(application.LoginStartInput) (application.Authorization, error)
-	completeFn  func(application.LoginCompleteInput) (application.ExternalIdentity, error)
+	beginFn     func(LoginStartInput) (Authorization, error)
+	completeFn  func(LoginCompleteInput) (ExternalIdentity, error)
 	beginCnt    int
 	completeCnt int
 }
 
 func (p *fakeLoginProvider) Name() string { return p.name }
 
-func (p *fakeLoginProvider) Begin(_ context.Context, in application.LoginStartInput) (application.Authorization, error) {
+func (p *fakeLoginProvider) Begin(_ context.Context, in LoginStartInput) (Authorization, error) {
 	p.beginCnt++
 	return p.beginFn(in)
 }
 
-func (p *fakeLoginProvider) Complete(_ context.Context, in application.LoginCompleteInput) (application.ExternalIdentity, error) {
+func (p *fakeLoginProvider) Complete(_ context.Context, in LoginCompleteInput) (ExternalIdentity, error) {
 	p.completeCnt++
 	return p.completeFn(in)
 }
 
-func newTestServiceWithProviders(repo repository, tokens testTokenStore, providers ...application.LoginProvider) *Service {
+func newTestServiceWithProviders(repo repository, tokens testTokenStore, providers ...LoginProvider) *Service {
 	return NewService(Dependencies{
 		Repository:        repo,
+		Passwords:         fakePasswordHasher{},
 		RefreshTokens:     tokens,
 		OAuthTransactions: tokens,
 		RecoveryTokens:    tokens,
 		MFA:               newFakeMFAStore(),
 		Mailer:            fakeMailer{},
-		Providers:         application.NewProviderRegistry(providers...),
+		Providers:         NewProviderRegistry(providers...),
 	}, AuthConfig{
 		JWTSecret:     "test-secret",
 		JWTAccessTTL:  time.Minute,
@@ -47,49 +46,49 @@ func newTestServiceWithProviders(repo repository, tokens testTokenStore, provide
 	})
 }
 
-func oauthErrorCode(t *testing.T, err error) application.OAuthErrorCode {
+func oauthErrorCode(t *testing.T, err error) OAuthErrorCode {
 	t.Helper()
-	var oauthErr *application.OAuthError
+	var oauthErr *OAuthError
 	if !errors.As(err, &oauthErr) {
-		t.Fatalf("expected *application.OAuthError, got %T: %v", err, err)
+		t.Fatalf("expected *OAuthError, got %T: %v", err, err)
 	}
 	return oauthErr.Code
 }
 
 const testOAuthVerifier = "client-code-verifier-0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ"
 
-func validLoginStart() application.LoginStartInput {
-	return application.LoginStartInput{
+func validLoginStart() LoginStartInput {
+	return LoginStartInput{
 		State:               "client state",
 		CodeChallenge:       pkceChallenge(testOAuthVerifier),
 		CodeChallengeMethod: "S256",
 	}
 }
 
-func validLoginExchange() loginExchangeInput {
-	return loginExchangeInput{Code: "code", State: "client state", CodeVerifier: testOAuthVerifier}
+func validLoginExchange() LoginExchangeInput {
+	return LoginExchangeInput{Code: "code", State: "client state", CodeVerifier: testOAuthVerifier}
 }
 
 func validFakeProvider(t *testing.T) (*fakeLoginProvider, *Service) {
 	t.Helper()
 	provider := &fakeLoginProvider{name: "fake"}
-	provider.beginFn = func(in application.LoginStartInput) (application.Authorization, error) {
+	provider.beginFn = func(in LoginStartInput) (Authorization, error) {
 		expected := validLoginStart()
 		if in.State != expected.State || in.CodeChallenge != expected.CodeChallenge || in.CodeChallengeMethod != expected.CodeChallengeMethod || strings.TrimSpace(in.Nonce) == "" {
 			t.Fatalf("unexpected begin input: %+v", in)
 		}
-		return application.Authorization{URL: "https://provider.example.test/authorize?" + url.Values{
+		return Authorization{URL: "https://provider.example.test/authorize?" + url.Values{
 			"state":                 {in.State},
 			"code_challenge":        {in.CodeChallenge},
 			"code_challenge_method": {in.CodeChallengeMethod},
 			"nonce":                 {in.Nonce},
 		}.Encode()}, nil
 	}
-	provider.completeFn = func(in application.LoginCompleteInput) (application.ExternalIdentity, error) {
+	provider.completeFn = func(in LoginCompleteInput) (ExternalIdentity, error) {
 		if in.Code != "code" || in.CodeVerifier != testOAuthVerifier || strings.TrimSpace(in.Nonce) == "" {
 			t.Fatalf("unexpected complete input: %+v", in)
 		}
-		return application.ExternalIdentity{
+		return ExternalIdentity{
 			Provider:      "fake",
 			Subject:       "subject-1",
 			Email:         "user@example.com",
@@ -122,20 +121,20 @@ func TestService_BeginLoginRejectsMissingStateOrNonS256PKCE(t *testing.T) {
 	provider, svc := validFakeProvider(t)
 	tests := []struct {
 		name string
-		in   application.LoginStartInput
+		in   LoginStartInput
 	}{
-		{name: "missing state", in: application.LoginStartInput{CodeChallenge: "challenge", CodeChallengeMethod: "S256"}},
-		{name: "missing challenge", in: application.LoginStartInput{State: "state", CodeChallengeMethod: "S256"}},
-		{name: "plain challenge method", in: application.LoginStartInput{State: "state", CodeChallenge: "challenge", CodeChallengeMethod: "plain"}},
-		{name: "short challenge", in: application.LoginStartInput{State: "state", CodeChallenge: "short", CodeChallengeMethod: "S256"}},
-		{name: "invalid challenge character", in: application.LoginStartInput{State: "state", CodeChallenge: strings.Repeat("!", 43), CodeChallengeMethod: "S256"}},
-		{name: "lowercase challenge method", in: application.LoginStartInput{State: "state", CodeChallenge: strings.Repeat("A", 43), CodeChallengeMethod: "s256"}},
+		{name: "missing state", in: LoginStartInput{CodeChallenge: "challenge", CodeChallengeMethod: "S256"}},
+		{name: "missing challenge", in: LoginStartInput{State: "state", CodeChallengeMethod: "S256"}},
+		{name: "plain challenge method", in: LoginStartInput{State: "state", CodeChallenge: "challenge", CodeChallengeMethod: "plain"}},
+		{name: "short challenge", in: LoginStartInput{State: "state", CodeChallenge: "short", CodeChallengeMethod: "S256"}},
+		{name: "invalid challenge character", in: LoginStartInput{State: "state", CodeChallenge: strings.Repeat("!", 43), CodeChallengeMethod: "S256"}},
+		{name: "lowercase challenge method", in: LoginStartInput{State: "state", CodeChallenge: strings.Repeat("A", 43), CodeChallengeMethod: "s256"}},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			_, err := svc.BeginLogin(context.Background(), "fake", tt.in)
-			if got := oauthErrorCode(t, err); got != application.OAuthStateInvalid {
-				t.Fatalf("oauth code = %q, want %q", got, application.OAuthStateInvalid)
+			if got := oauthErrorCode(t, err); got != OAuthStateInvalid {
+				t.Fatalf("oauth code = %q, want %q", got, OAuthStateInvalid)
 			}
 			if provider.beginCnt != 0 {
 				t.Fatal("provider must not receive an invalid state/PKCE request")
@@ -163,8 +162,8 @@ func TestService_ExchangeLoginRejectsIdentityFromAnotherProvider(t *testing.T) {
 	if _, err := svc.BeginLogin(context.Background(), "fake", validLoginStart()); err != nil {
 		t.Fatalf("begin login: %v", err)
 	}
-	provider.completeFn = func(application.LoginCompleteInput) (application.ExternalIdentity, error) {
-		return application.ExternalIdentity{
+	provider.completeFn = func(LoginCompleteInput) (ExternalIdentity, error) {
+		return ExternalIdentity{
 			Provider:      "another-provider",
 			Subject:       "subject-1",
 			Email:         "user@example.com",
@@ -172,8 +171,8 @@ func TestService_ExchangeLoginRejectsIdentityFromAnotherProvider(t *testing.T) {
 		}, nil
 	}
 	_, err := svc.ExchangeLogin(context.Background(), "fake", validLoginExchange())
-	if got := oauthErrorCode(t, err); got != application.OAuthFailed {
-		t.Fatalf("oauth code = %q, want %q", got, application.OAuthFailed)
+	if got := oauthErrorCode(t, err); got != OAuthFailed {
+		t.Fatalf("oauth code = %q, want %q", got, OAuthFailed)
 	}
 }
 
@@ -181,20 +180,20 @@ func TestService_ExchangeLoginMapsProviderErrorsToControlledCodes(t *testing.T)
 	tests := []struct {
 		name          string
 		providerError error
-		wantCode      application.OAuthErrorCode
+		wantCode      OAuthErrorCode
 	}{
-		{name: "provider exchange failure", providerError: application.NewProviderFailure(errors.New("exchange failed")), wantCode: application.OAuthFailed},
-		{name: "provider unavailable", providerError: application.NewProviderUnavailable(errors.New("upstream timeout")), wantCode: application.OAuthProviderUnavailable},
+		{name: "provider exchange failure", providerError: NewProviderFailure(errors.New("exchange failed")), wantCode: OAuthFailed},
+		{name: "provider unavailable", providerError: NewProviderUnavailable(errors.New("upstream timeout")), wantCode: OAuthProviderUnavailable},
 	}
 
 	for _, tt := range tests {
-		 t.Run(tt.name, func(t *testing.T) {
+		t.Run(tt.name, func(t *testing.T) {
 			provider, svc := validFakeProvider(t)
 			if _, err := svc.BeginLogin(context.Background(), "fake", validLoginStart()); err != nil {
 				t.Fatalf("begin login: %v", err)
 			}
-			provider.completeFn = func(application.LoginCompleteInput) (application.ExternalIdentity, error) {
-				return application.ExternalIdentity{}, tt.providerError
+			provider.completeFn = func(LoginCompleteInput) (ExternalIdentity, error) {
+				return ExternalIdentity{}, tt.providerError
 			}
 			_, err := svc.ExchangeLogin(context.Background(), "fake", validLoginExchange())
 			if got := oauthErrorCode(t, err); got != tt.wantCode {
@@ -208,12 +207,12 @@ func TestService_ExchangeLoginRejectsMissingStatePKCEAndCode(t *testing.T) {
 	_, svc := validFakeProvider(t)
 	tests := []struct {
 		name string
-		in   loginExchangeInput
-		want application.OAuthErrorCode
+		in   LoginExchangeInput
+		want OAuthErrorCode
 	}{
-		{name: "missing state", in: loginExchangeInput{Code: "code", CodeVerifier: testOAuthVerifier}, want: application.OAuthStateInvalid},
-		{name: "missing verifier", in: loginExchangeInput{Code: "code", State: "state"}, want: application.OAuthStateInvalid},
-		{name: "missing code", in: loginExchangeInput{State: "state", CodeVerifier: testOAuthVerifier}, want: application.OAuthFailed},
+		{name: "missing state", in: LoginExchangeInput{Code: "code", CodeVerifier: testOAuthVerifier}, want: OAuthStateInvalid},
+		{name: "missing verifier", in: LoginExchangeInput{Code: "code", State: "state"}, want: OAuthStateInvalid},
+		{name: "missing code", in: LoginExchangeInput{State: "state", CodeVerifier: testOAuthVerifier}, want: OAuthFailed},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
@@ -232,10 +231,10 @@ func TestService_ExchangeLoginConsumesStateAndBindsThePKCEVerifier(t *testing.T)
 	}
 	wrong := validLoginExchange()
 	wrong.CodeVerifier = testOAuthVerifier + "x"
-	if _, err := svc.ExchangeLogin(context.Background(), "fake", wrong); oauthErrorCode(t, err) != application.OAuthStateInvalid {
+	if _, err := svc.ExchangeLogin(context.Background(), "fake", wrong); oauthErrorCode(t, err) != OAuthStateInvalid {
 		t.Fatalf("wrong verifier should be rejected as state invalid: %v", err)
 	}
-	if _, err := svc.ExchangeLogin(context.Background(), "fake", validLoginExchange()); oauthErrorCode(t, err) != application.OAuthStateInvalid {
+	if _, err := svc.ExchangeLogin(context.Background(), "fake", validLoginExchange()); oauthErrorCode(t, err) != OAuthStateInvalid {
 		t.Fatalf("a rejected exchange must consume the one-time transaction: %v", err)
 	}
 	if provider.completeCnt != 0 {
@@ -249,18 +248,18 @@ func TestService_UnconfiguredProviderDoesNotBuildAURL(t *testing.T) {
 	if start != nil {
 		t.Fatalf("unconfigured provider returned a login start: %+v", start)
 	}
-	if got := oauthErrorCode(t, err); got != application.OAuthProviderUnavailable {
-		t.Fatalf("oauth code = %q, want %q", got, application.OAuthProviderUnavailable)
+	if got := oauthErrorCode(t, err); got != OAuthProviderUnavailable {
+		t.Fatalf("oauth code = %q, want %q", got, OAuthProviderUnavailable)
 	}
 	_, err = svc.ExchangeLogin(context.Background(), "google", validLoginExchange())
-	if got := oauthErrorCode(t, err); got != application.OAuthProviderUnavailable {
-		t.Fatalf("exchange oauth code = %q, want %q", got, application.OAuthProviderUnavailable)
+	if got := oauthErrorCode(t, err); got != OAuthProviderUnavailable {
+		t.Fatalf("exchange oauth code = %q, want %q", got, OAuthProviderUnavailable)
 	}
 }
 
 func TestProviderRegistry_UsesProviderNameAsTheOnlyLookupKey(t *testing.T) {
 	provider := &fakeLoginProvider{name: "fake"}
-	registry := application.NewProviderRegistry(provider)
+	registry := NewProviderRegistry(provider)
 	if got, ok := registry.Lookup("fake"); !ok || got != provider {
 		t.Fatalf("registry lookup = (%v, %v), want fake provider", got, ok)
 	}
@@ -270,17 +269,17 @@ func TestProviderRegistry_UsesProviderNameAsTheOnlyLookupKey(t *testing.T) {
 }
 
 func TestService_BeginLoginRejectsEmptyProviderAuthorizationURL(t *testing.T) {
-	provider := &fakeLoginProvider{name: "fake", beginFn: func(application.LoginStartInput) (application.Authorization, error) {
-		return application.Authorization{}, nil
+	provider := &fakeLoginProvider{name: "fake", beginFn: func(LoginStartInput) (Authorization, error) {
+		return Authorization{}, nil
 	}}
 	svc := newTestServiceWithProviders(&fakeRepo{}, newFakeTokenStore(), provider)
 	_, err := svc.BeginLogin(context.Background(), "fake", validLoginStart())
-	if got := oauthErrorCode(t, err); got != application.OAuthProviderUnavailable {
-		t.Fatalf("oauth code = %q, want %q", got, application.OAuthProviderUnavailable)
+	if got := oauthErrorCode(t, err); got != OAuthProviderUnavailable {
+		t.Fatalf("oauth code = %q, want %q", got, OAuthProviderUnavailable)
 	}
 	if strings.Contains(err.Error(), "Location") {
 		t.Fatalf("empty authorization must not become a redirect: %v", err)
 	}
 }
 
-var _ application.LoginProvider = (*fakeLoginProvider)(nil)
+var _ LoginProvider = (*fakeLoginProvider)(nil)

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

@@ -1,6 +1,3 @@
-// Package application contains auth use cases and ports that are independent
-// of Gin, GORM models, and HTTP error payloads. Adapters in the parent user
-// package translate those contracts at the feature boundary.
 package application
 
 import (
@@ -8,55 +5,24 @@ import (
 	"errors"
 	"fmt"
 
+	"{{goModule}}/internal/app/user/domain"
+	"{{goModule}}/internal/app/user/ports"
+
 	"github.com/google/uuid"
 )
 
-var ErrInvalidToken = errors.New("invalid or expired one-time token")
-
-type Identity struct {
-	ID           uuid.UUID
-	UserID       uuid.UUID
-	PasswordHash string
-}
-
-type User struct {
-	ID            uuid.UUID
-	EmailVerified bool
-}
-
-// RecoveryRepository is an outbound port owned by the recovery use case.
-// Implementations map persistence rows to these plain application values.
-type RecoveryRepository interface {
-	FindIdentity(context.Context, uuid.UUID) (*Identity, error)
-	UpdateIdentity(context.Context, *Identity) error
-	FindUser(context.Context, uuid.UUID) (*User, error)
-	UpdateUser(context.Context, *User) error
-}
-
-type RecoveryTokens 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)
-}
-
-type PasswordHasher interface {
-	Hash(string) (string, error)
-}
-
 type Recovery struct {
-	repo   RecoveryRepository
-	tokens RecoveryTokens
+	repo   ports.UserRepository
+	tokens ports.RecoveryTokenStore
 	hasher PasswordHasher
 }
 
-func NewRecovery(repo RecoveryRepository, tokens RecoveryTokens, hasher PasswordHasher) *Recovery {
+func NewRecovery(repo ports.UserRepository, tokens ports.RecoveryTokenStore, hasher PasswordHasher) *Recovery {
 	return &Recovery{repo: repo, tokens: tokens, hasher: hasher}
 }
 
-// ResetPassword consumes the token and updates the identity in one unit of
-// work. Postgres-backed token adapters run both writes through the same DB
-// transaction; the contract is deliberately a port so another adapter can
-// provide an equivalent retry-safe boundary.
+// ResetPassword consumes the token and updates the local identity in one
+// unit of work. The token adapter owns the transaction boundary.
 func (r *Recovery) ResetPassword(ctx context.Context, tokenHash, newPassword string) (uuid.UUID, error) {
 	hash, err := r.hasher.Hash(newPassword)
 	if err != nil {
@@ -70,14 +36,17 @@ func (r *Recovery) ResetPassword(ctx context.Context, tokenHash, newPassword str
 			return fmt.Errorf("consume password reset token: %w", err)
 		}
 		if !ok {
-			return ErrInvalidToken
+			return domain.ErrInvalidToken
 		}
 
-		identity, err := r.repo.FindIdentity(txctx, id)
+		identity, err := r.repo.FindIdentity(txctx, id, domain.ProviderLocal)
 		if err != nil {
 			return fmt.Errorf("find local identity: %w", err)
 		}
-		identity.PasswordHash = hash
+		if identity.PasswordHash == nil {
+			return errors.New("local identity has no password")
+		}
+		identity.PasswordHash = &hash
 		if err := r.repo.UpdateIdentity(txctx, identity); err != nil {
 			return fmt.Errorf("update password: %w", err)
 		}
@@ -95,10 +64,10 @@ func (r *Recovery) VerifyEmail(ctx context.Context, tokenHash string) (uuid.UUID
 			return fmt.Errorf("consume email verification token: %w", err)
 		}
 		if !ok {
-			return ErrInvalidToken
+			return domain.ErrInvalidToken
 		}
 
-		user, err := r.repo.FindUser(txctx, id)
+		user, err := r.repo.FindByID(txctx, id)
 		if err != nil {
 			return fmt.Errorf("find user for email verification: %w", err)
 		}

package/templates/add/auth/internal/app/user/{recovery_service.go.hbs → application/recovery_service.go.hbs}

@@ -1,4 +1,4 @@
-package user
+package application
 
 import (
 	"context"
@@ -6,9 +6,7 @@ import (
 	"fmt"
 	"log/slog"
 
-	"{{goModule}}/internal/app/user/application"
-	"{{goModule}}/internal/app/user/model"
-	"{{goModule}}/internal/shared/apperror"
+	"{{goModule}}/internal/app/user/domain"
 
 	"github.com/google/uuid"
 )
@@ -29,17 +27,17 @@ func (s *Service) ForgotPassword(ctx context.Context, email string) error {
 	if err != nil {
 		return nil
 	}
-	ident, err := s.repo.FindIdentity(ctx, u.ID, model.ProviderLocal)
+	ident, err := s.repo.FindIdentity(ctx, u.ID, domain.ProviderLocal)
 	if err != nil || ident.PasswordHash == nil {
 		return nil
 	}
 
 	raw, err := randomToken()
 	if err != nil {
-		return apperror.NewInternal(err)
+		return fmt.Errorf("generate password reset token: %w", err)
 	}
 	if err := s.recoveryTokens.SetPasswordResetToken(ctx, hashToken(raw), u.ID, s.config.PasswordResetTTL); err != nil {
-		return apperror.NewInternal(err)
+		return fmt.Errorf("store password reset token: %w", err)
 	}
 
 	link := s.config.PasswordResetURL + "?token=" + raw
@@ -58,23 +56,23 @@ func (s *Service) ResetPassword(ctx context.Context, rawToken, newPassword strin
 	tokenHash := hashToken(rawToken)
 	userID, err := s.recovery.ResetPassword(ctx, tokenHash, newPassword)
 	if err != nil {
-		if errors.Is(err, application.ErrInvalidToken) {
+		if errors.Is(err, domain.ErrInvalidToken) {
 			return errInvalidToken()
 		}
-		return apperror.NewInternal(fmt.Errorf("reset password: %w", err))
+		return fmt.Errorf("reset password: %w", err)
 	}
 	if err := s.refreshTokens.RevokeAllRefreshTokens(ctx, userID); err != nil {
 		if restoreErr := s.recoveryTokens.SetPasswordResetToken(ctx, tokenHash, userID, s.config.PasswordResetTTL); restoreErr != nil {
-			return apperror.NewInternal(fmt.Errorf("revoke sessions after password reset: %w; restore reset token for retry: %v", err, restoreErr))
+			return fmt.Errorf("revoke sessions after password reset: %w; restore reset token for retry: %v", err, restoreErr)
 		}
-		return apperror.NewInternal(fmt.Errorf("revoke sessions after password reset (reset token restored for retry): %w", err))
+		return fmt.Errorf("revoke sessions after password reset (reset token restored for retry): %w", err)
 	}
 	return nil
 }
 
 // sendVerificationEmail issues a one-time token and sends its link. It is
 // shared by registration and the authenticated resend flow.
-func (s *Service) sendVerificationEmail(ctx context.Context, u *model.User) {
+func (s *Service) sendVerificationEmail(ctx context.Context, u *domain.User) {
 	raw, err := randomToken()
 	if err != nil {
 		slog.Error("generate email verification token", "error", err)
@@ -93,7 +91,7 @@ func (s *Service) sendVerificationEmail(ctx context.Context, u *model.User) {
 func (s *Service) ResendVerificationEmail(ctx context.Context, userID uuid.UUID) error {
 	u, err := s.repo.FindByID(ctx, userID)
 	if err != nil {
-		return apperror.NewInternal(err)
+		return wrapFindErr(err)
 	}
 	if u.EmailVerified {
 		return errAlreadyVerified()
@@ -105,10 +103,10 @@ func (s *Service) ResendVerificationEmail(ctx context.Context, userID uuid.UUID)
 func (s *Service) VerifyEmail(ctx context.Context, rawToken string) error {
 	_, err := s.recovery.VerifyEmail(ctx, hashToken(rawToken))
 	if err != nil {
-		if errors.Is(err, application.ErrInvalidToken) {
+		if errors.Is(err, domain.ErrInvalidToken) {
 			return errInvalidToken()
 		}
-		return apperror.NewInternal(fmt.Errorf("verify email: %w", err))
+		return fmt.Errorf("verify email: %w", err)
 	}
 	return nil
 }

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

@@ -0,0 +1,145 @@
+package application
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"time"
+
+	"{{goModule}}/internal/app/user/domain"
+	"{{goModule}}/internal/app/user/ports"
+
+	"github.com/google/uuid"
+)
+
+// repository is a package-local name used by focused application tests and
+// generated method extensions. The actual contract is owned by ports.
+type repository = ports.UserRepository
+
+// Service coordinates user authentication use cases. Transport concerns stay
+// in the inbound adapter and persistence concerns stay in outbound adapters.
+type Service struct {
+	repo              ports.UserRepository
+	passwords         ports.PasswordHasher
+	refreshTokens     ports.RefreshTokenStore
+	oauthTransactions ports.OAuthTransactionStore
+	recoveryTokens    ports.RecoveryTokenStore
+	mfa               ports.MFAStore
+	mailer            ports.AuthMailer
+	providers         ProviderRegistry
+	recovery          *Recovery
+	config            AuthConfig
+	roles             ports.RoleChecker
+	now               func() time.Time
+	// go-scaffold:user-service-fields
+}
+
+// NewService is the application composition constructor. It accepts explicit
+// ports and policy rather than a framework or catch-all infrastructure object.
+func NewService(deps Dependencies, cfg AuthConfig) *Service {
+	if deps.Passwords == nil {
+		panic("user application: password hasher is required")
+	}
+	if cfg.JWTAccessTTL <= 0 {
+		cfg.JWTAccessTTL = 15 * time.Minute
+	}
+	if cfg.JWTRefreshTTL <= 0 {
+		cfg.JWTRefreshTTL = 12 * time.Hour
+	}
+	cfg.JWTRefreshMaxTTL = defaultDuration(cfg.JWTRefreshMaxTTL, cfg.JWTRefreshTTL)
+	cfg.OAuthStateTTL = defaultDuration(cfg.OAuthStateTTL, 10*time.Minute)
+	if cfg.MFA.RecoveryCodeCount == 0 {
+		cfg.MFA.RecoveryCodeCount = defaultMFACodes
+	}
+	clock := deps.Clock
+	if clock == nil {
+		clock = time.Now
+	}
+	return &Service{
+		repo:              deps.Repository,
+		passwords:         deps.Passwords,
+		refreshTokens:     deps.RefreshTokens,
+		oauthTransactions: deps.OAuthTransactions,
+		recoveryTokens:    deps.RecoveryTokens,
+		mfa:               deps.MFA,
+		mailer:            deps.Mailer,
+		providers:         deps.Providers,
+		recovery:          NewRecovery(deps.Repository, deps.RecoveryTokens, deps.Passwords),
+		config:            cfg,
+		roles:             deps.Roles,
+		now:               clock,
+		// go-scaffold:user-service-init
+	}
+}
+
+func defaultDuration(value, fallback time.Duration) time.Duration {
+	if value > 0 {
+		return value
+	}
+	return fallback
+}
+
+func (s *Service) clock() time.Time {
+	if s.now == nil {
+		return time.Now()
+	}
+	return s.now()
+}
+
+// normalizeEmail is applied at every boundary an address enters the service
+// through. The database stores the canonical lower-case representation.
+func normalizeEmail(email string) string {
+	return strings.ToLower(strings.TrimSpace(email))
+}
+
+// SetRole validates the role against the role catalog before persisting it.
+func (s *Service) SetRole(ctx context.Context, userID uuid.UUID, roleCode string) (*domain.User, error) {
+	u, err := s.repo.FindByID(ctx, userID)
+	if err != nil {
+		return nil, wrapFindErr(err)
+	}
+	if s.roles == nil {
+		return nil, fmt.Errorf("role checker is not configured")
+	}
+	exists, err := s.roles.CodeExists(ctx, roleCode)
+	if err != nil {
+		return nil, fmt.Errorf("check role code: %w", err)
+	}
+	if !exists {
+		return nil, errUnknownRole()
+	}
+	u.Role = roleCode
+	if err := s.repo.UpdateUser(ctx, u); err != nil {
+		return nil, fmt.Errorf("update user role: %w", err)
+	}
+	return u, nil
+}
+
+// ServicePort is the inbound application boundary. HTTP, jobs, and future
+// transports depend on this capability set instead of the concrete service.
+type ServicePort interface {
+	// go-scaffold:service-interface
+	Register(context.Context, RegisterInput) (*AuthResult, error)
+	Login(context.Context, LoginInput) (*AuthResult, error)
+	Refresh(context.Context, string) (*AuthResponse, error)
+	Logout(context.Context, string) error
+	LogoutAll(context.Context, uuid.UUID) error
+	ForgotPassword(context.Context, string) error
+	ResetPassword(context.Context, string, string) error
+	VerifyEmail(context.Context, string) error
+	ResendVerificationEmail(context.Context, uuid.UUID) error
+	BeginLogin(context.Context, string, LoginStartInput) (*Authorization, error)
+	ExchangeLogin(context.Context, string, LoginExchangeInput) (*AuthResult, error)
+	VerifyMFA(context.Context, string, string) (*AuthResponse, error)
+	MFAStatus(context.Context, uuid.UUID) (MFAStatus, error)
+	SetupMFA(context.Context, uuid.UUID) (*MFASetup, error)
+	ConfirmMFA(context.Context, uuid.UUID, string) ([]string, error)
+	DisableMFA(context.Context, uuid.UUID, string) error
+	Get(context.Context, uuid.UUID) (*domain.User, error)
+	List(context.Context, int, int) ([]domain.User, error)
+	SetRole(context.Context, uuid.UUID, string) (*domain.User, error)
+}
+
+var _ ServicePort = (*Service)(nil)
+
+// go-scaffold:service-methods