@nakedev/go-scaffold 0.4.0 → 0.5.0

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

@@ -0,0 +1,200 @@
+package application
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"testing"
+	"time"
+
+	"{{goModule}}/internal/app/user/domain"
+
+	"github.com/google/uuid"
+)
+
+const testMFAEncryptionKey = "MDEyMzQ1Njc4OWFiY2RlZjAxMjM0NTY3ODlhYmNkZWY="
+
+func configuredMFATestService(t *testing.T) (*Service, *fakeMFAStore, uuid.UUID, time.Time) {
+	t.Helper()
+	userID := uuid.New()
+	mfa := newFakeMFAStore()
+	svc := newTestService(&fakeRepo{user: &domain.User{ID: userID, Email: "mfa@example.com"}}, newFakeTokenStore())
+	now := time.Now()
+	svc.mfa = mfa
+	svc.now = func() time.Time { return now }
+	svc.config.MFA = MFASettings{
+		Enabled:           true,
+		Issuer:            "Example",
+		EncryptionKey:     testMFAEncryptionKey,
+		ChallengeTTL:      5 * time.Minute,
+		TOTPWindow:        1,
+		RecoveryCodeCount: 10,
+	}
+	return svc, mfa, userID, now
+}
+
+func TestTOTPCodeMatchesRFC6238SHA1Vector(t *testing.T) {
+	secret := "GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ"
+	code, err := totpCode(secret, time.Unix(59, 0))
+	if err != nil {
+		t.Fatalf("generate TOTP: %v", err)
+	}
+	if code != "287082" {
+		t.Fatalf("expected RFC 6238 six-digit code 287082, got %s", code)
+	}
+}
+
+func TestMFADefaultIsDisabled(t *testing.T) {
+	userID := uuid.New()
+	svc := newTestService(&fakeRepo{user: &domain.User{ID: userID, Email: "default@example.com"}}, newFakeTokenStore())
+
+	status, err := svc.MFAStatus(context.Background(), userID)
+	if err != nil {
+		t.Fatalf("read default MFA status: %v", err)
+	}
+	if status.Available || status.Enabled {
+		t.Fatalf("MFA must be disabled and unavailable by default: %+v", status)
+	}
+}
+
+func TestValidateMFASettingsRejectsUnsafeEnabledConfiguration(t *testing.T) {
+	valid := MFASettings{
+		Enabled:           true,
+		EncryptionKey:     testMFAEncryptionKey,
+		ChallengeTTL:      5 * time.Minute,
+		TOTPWindow:        1,
+		RecoveryCodeCount: 10,
+	}
+	if err := ValidateMFASettings(valid); err != nil {
+		t.Fatalf("valid MFA settings rejected: %v", err)
+	}
+
+	for name, settings := range map[string]MFASettings{
+		"missing encryption key":  validWithMFAOverride(valid, func(s *MFASettings) { s.EncryptionKey = "" }),
+		"non-positive challenge":  validWithMFAOverride(valid, func(s *MFASettings) { s.ChallengeTTL = 0 }),
+		"wide TOTP window":        validWithMFAOverride(valid, func(s *MFASettings) { s.TOTPWindow = 4 }),
+		"too few recovery codes":  validWithMFAOverride(valid, func(s *MFASettings) { s.RecoveryCodeCount = 4 }),
+		"too many recovery codes": validWithMFAOverride(valid, func(s *MFASettings) { s.RecoveryCodeCount = 21 }),
+	} {
+		if err := ValidateMFASettings(settings); err == nil {
+			t.Errorf("%s: expected invalid enabled configuration to fail", name)
+		}
+	}
+	if err := ValidateMFASettings(MFASettings{Enabled: false}); err != nil {
+		t.Fatalf("disabled MFA should not require an encryption key: %v", err)
+	}
+}
+
+func validWithMFAOverride(base MFASettings, override func(*MFASettings)) MFASettings {
+	copy := base
+	override(&copy)
+	return copy
+}
+
+func TestMFAEnrollmentIsPendingUntilTOTPConfirmation(t *testing.T) {
+	svc, store, userID, now := configuredMFATestService(t)
+	ctx := context.Background()
+
+	setup, err := svc.SetupMFA(ctx, userID)
+	if err != nil {
+		t.Fatalf("setup MFA: %v", err)
+	}
+	if setup.Secret == "" || !strings.HasPrefix(setup.OTPAuthURI, "otpauth://totp/") {
+		t.Fatalf("unexpected setup response: %+v", setup)
+	}
+	if strings.Contains(store.enrollments[userID].EncryptedSecret, setup.Secret) {
+		t.Fatal("MFA secret must not be stored in plaintext")
+	}
+
+	status, err := svc.MFAStatus(ctx, userID)
+	if err != nil || !status.Available || status.Enabled {
+		t.Fatalf("expected available but disabled pending enrollment: %+v, %v", status, err)
+	}
+	code, _ := totpCode(setup.Secret, now)
+	codes, err := svc.ConfirmMFA(ctx, userID, code)
+	if err != nil {
+		t.Fatalf("confirm MFA: %v", err)
+	}
+	if len(codes) != 10 {
+		t.Fatalf("expected 10 recovery codes, got %d", len(codes))
+	}
+	status, err = svc.MFAStatus(ctx, userID)
+	if err != nil || !status.Enabled {
+		t.Fatalf("expected enabled MFA status: %+v, %v", status, err)
+	}
+}
+
+func TestMFAChallengeIsRequiredAndOneUse(t *testing.T) {
+	svc, _, userID, now := configuredMFATestService(t)
+	ctx := context.Background()
+	secret, err := newTOTPSecret()
+	if err != nil {
+		t.Fatalf("secret: %v", err)
+	}
+	encrypted, err := encryptMFASecret(testMFAEncryptionKey, secret)
+	if err != nil {
+		t.Fatalf("encrypt: %v", err)
+	}
+	if err := svc.mfa.ConfirmEnrollment(ctx, userID, encrypted, []string{}); err == nil {
+		t.Fatal("expected store to reject an enrollment without recovery codes")
+	}
+	// Use the service path so the exact recovery-code policy is exercised.
+	if err := svc.mfa.PutPendingEnrollment(ctx, userID, encrypted); err != nil {
+		t.Fatalf("pending: %v", err)
+	}
+	code, _ := totpCode(secret, now)
+	if _, err := svc.ConfirmMFA(ctx, userID, code); err != nil {
+		t.Fatalf("confirm: %v", err)
+	}
+
+	result, err := svc.completeLogin(ctx, &domain.User{ID: userID, Email: "mfa@example.com"})
+	if err != nil || result.MFAChallenge == "" || result.AuthResponse != nil {
+		t.Fatalf("expected pre-session MFA challenge: %+v, %v", result, err)
+	}
+	auth, err := svc.VerifyMFA(ctx, result.MFAChallenge, code)
+	if err != nil || auth == nil || auth.AccessToken == "" || auth.RefreshToken == "" {
+		t.Fatalf("verify MFA: %+v, %v", auth, err)
+	}
+	if _, err := svc.VerifyMFA(ctx, result.MFAChallenge, code); codeOfMFAError(err) != "AUTH_MFA_INVALID" {
+		t.Fatalf("expected one-use challenge rejection, got %v", err)
+	}
+}
+
+func TestMFARecoveryCodeIsOneUse(t *testing.T) {
+	svc, _, userID, now := configuredMFATestService(t)
+	ctx := context.Background()
+	setup, err := svc.SetupMFA(ctx, userID)
+	if err != nil {
+		t.Fatalf("setup: %v", err)
+	}
+	code, _ := totpCode(setup.Secret, now)
+	recoveryCodes, err := svc.ConfirmMFA(ctx, userID, code)
+	if err != nil {
+		t.Fatalf("confirm: %v", err)
+	}
+	result, err := svc.completeLogin(ctx, &domain.User{ID: userID, Email: "mfa@example.com"})
+	if err != nil {
+		t.Fatalf("login challenge: %v", err)
+	}
+	if _, err := svc.VerifyMFA(ctx, result.MFAChallenge, recoveryCodes[0]); err != nil {
+		t.Fatalf("verify with recovery code: %v", err)
+	}
+	result, err = svc.completeLogin(ctx, &domain.User{ID: userID, Email: "mfa@example.com"})
+	if err != nil {
+		t.Fatalf("second login challenge: %v", err)
+	}
+	if _, err := svc.VerifyMFA(ctx, result.MFAChallenge, recoveryCodes[0]); codeOfMFAError(err) != "AUTH_MFA_INVALID" {
+		t.Fatalf("expected consumed recovery code rejection, got %v", err)
+	}
+}
+
+func codeOfMFAError(err error) string {
+	if err == nil {
+		return ""
+	}
+	var ruleErr *domain.RuleError
+	if errors.As(err, &ruleErr) {
+		return ruleErr.Code
+	}
+	return ""
+}

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

@@ -0,0 +1,132 @@
+// Package application contains auth use cases and ports that are independent
+// of Gin, GORM models, OAuth SDKs, and HTTP error payloads.
+package application
+
+import (
+	"context"
+	"errors"
+	"fmt"
+)
+
+// LoginProvider is the outbound port for an external authorization-code
+// provider. Implementations own provider SDKs, token exchange, claims/userinfo
+// validation, and provider-specific HTTP details. The user application only
+// sees these small, provider-neutral values.
+type LoginProvider interface {
+	Name() string
+	Begin(context.Context, LoginStartInput) (Authorization, error)
+	Complete(context.Context, LoginCompleteInput) (ExternalIdentity, error)
+}
+
+type LoginStartInput struct {
+	State               string
+	CodeChallenge       string
+	CodeChallengeMethod string
+	Nonce               string
+}
+
+type Authorization struct {
+	URL string
+}
+
+type LoginCompleteInput struct {
+	Code         string
+	CodeVerifier string
+	Nonce        string
+}
+
+// ExternalIdentity is the normalized identity returned by every provider
+// adapter. Provider must be the registry name and Subject must be the
+// provider's stable subject identifier, never an email address.
+type ExternalIdentity struct {
+	Provider      string
+	Subject       string
+	Email         string
+	EmailVerified bool
+	Name          string
+	AvatarURL     string
+}
+
+// ProviderRegistry is an immutable-by-convention lookup boundary. It is
+// assembled in the composition root from providers whose configuration is
+// complete; an absent provider is therefore an expected unavailable state,
+// not an invitation to construct an empty redirect URL.
+type ProviderRegistry struct {
+	providers map[string]LoginProvider
+}
+
+func NewProviderRegistry(providers ...LoginProvider) ProviderRegistry {
+	byName := make(map[string]LoginProvider, len(providers))
+	for _, provider := range providers {
+		if provider == nil || provider.Name() == "" {
+			continue
+		}
+		byName[provider.Name()] = provider
+	}
+	return ProviderRegistry{providers: byName}
+}
+
+func (r ProviderRegistry) Lookup(name string) (LoginProvider, bool) {
+	provider, ok := r.providers[name]
+	return provider, ok
+}
+
+type OAuthErrorCode string
+
+const (
+	OAuthDenied              OAuthErrorCode = "oauth_denied"
+	OAuthStateInvalid        OAuthErrorCode = "oauth_state_invalid"
+	OAuthProviderUnavailable OAuthErrorCode = "oauth_provider_unavailable"
+	OAuthFailed              OAuthErrorCode = "oauth_failed"
+)
+
+// OAuthError is the public, controlled error contract for the browser login
+// start/exchange boundary. Cause is retained only for server-side logs and
+// unwrapping; handlers never serialize Error() to the browser.
+type OAuthError struct {
+	Code  OAuthErrorCode
+	Cause error
+}
+
+func (e *OAuthError) Error() string {
+	if e.Cause == nil {
+		return string(e.Code)
+	}
+	return fmt.Sprintf("%s: %v", e.Code, e.Cause)
+}
+
+func (e *OAuthError) Unwrap() error { return e.Cause }
+
+func NewOAuthError(code OAuthErrorCode, cause error) *OAuthError {
+	return &OAuthError{Code: code, Cause: cause}
+}
+
+type ProviderError struct {
+	Unavailable bool
+	Cause       error
+}
+
+func (e *ProviderError) Error() string {
+	if e.Cause == nil {
+		if e.Unavailable {
+			return "oauth provider unavailable"
+		}
+		return "oauth provider failed"
+	}
+	return e.Cause.Error()
+}
+
+func (e *ProviderError) Unwrap() error { return e.Cause }
+
+func NewProviderUnavailable(cause error) error {
+	return &ProviderError{Unavailable: true, Cause: cause}
+}
+
+func NewProviderFailure(cause error) error {
+	return &ProviderError{Cause: cause}
+}
+
+func IsProviderUnavailable(err error) bool {
+	var providerErr *ProviderError
+	return errors.As(err, &providerErr) && providerErr.Unavailable
+}

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

@@ -0,0 +1,285 @@
+package application
+
+import (
+	"context"
+	"errors"
+	"net/url"
+	"strings"
+	"testing"
+	"time"
+)
+
+type fakeLoginProvider struct {
+	name        string
+	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 LoginStartInput) (Authorization, error) {
+	p.beginCnt++
+	return p.beginFn(in)
+}
+
+func (p *fakeLoginProvider) Complete(_ context.Context, in LoginCompleteInput) (ExternalIdentity, error) {
+	p.completeCnt++
+	return p.completeFn(in)
+}
+
+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:         NewProviderRegistry(providers...),
+	}, AuthConfig{
+		JWTSecret:     "test-secret",
+		JWTAccessTTL:  time.Minute,
+		JWTRefreshTTL: time.Hour,
+	})
+}
+
+func oauthErrorCode(t *testing.T, err error) OAuthErrorCode {
+	t.Helper()
+	var oauthErr *OAuthError
+	if !errors.As(err, &oauthErr) {
+		t.Fatalf("expected *OAuthError, got %T: %v", err, err)
+	}
+	return oauthErr.Code
+}
+
+const testOAuthVerifier = "client-code-verifier-0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ"
+
+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 validFakeProvider(t *testing.T) (*fakeLoginProvider, *Service) {
+	t.Helper()
+	provider := &fakeLoginProvider{name: "fake"}
+	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 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 LoginCompleteInput) (ExternalIdentity, error) {
+		if in.Code != "code" || in.CodeVerifier != testOAuthVerifier || strings.TrimSpace(in.Nonce) == "" {
+			t.Fatalf("unexpected complete input: %+v", in)
+		}
+		return ExternalIdentity{
+			Provider:      "fake",
+			Subject:       "subject-1",
+			Email:         "user@example.com",
+			EmailVerified: true,
+			Name:          "User",
+		}, nil
+	}
+	return provider, newTestServiceWithProviders(&fakeRepo{}, newFakeTokenStore(), provider)
+}
+
+func TestService_BeginLoginUsesRegistryAndPreservesClientStateAndS256PKCE(t *testing.T) {
+	provider, svc := validFakeProvider(t)
+	start, err := svc.BeginLogin(context.Background(), "fake", validLoginStart())
+	if err != nil {
+		t.Fatalf("begin login: %v", err)
+	}
+	if provider.beginCnt != 1 || start == nil || start.URL == "" {
+		t.Fatalf("unexpected begin result: provider=%+v start=%+v", provider, start)
+	}
+	parsed, err := url.Parse(start.URL)
+	if err != nil {
+		t.Fatalf("parse authorization URL: %v", err)
+	}
+	if parsed.Query().Get("state") != "client state" || parsed.Query().Get("code_challenge") != pkceChallenge(testOAuthVerifier) || parsed.Query().Get("code_challenge_method") != "S256" || parsed.Query().Get("nonce") == "" {
+		t.Fatalf("authorization URL did not preserve client state/PKCE: %s", start.URL)
+	}
+}
+
+func TestService_BeginLoginRejectsMissingStateOrNonS256PKCE(t *testing.T) {
+	provider, svc := validFakeProvider(t)
+	tests := []struct {
+		name string
+		in   LoginStartInput
+	}{
+		{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 != 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")
+			}
+		})
+	}
+}
+
+func TestService_ExchangeLoginReturnsSessionForNormalizedProviderIdentity(t *testing.T) {
+	provider, svc := validFakeProvider(t)
+	if _, err := svc.BeginLogin(context.Background(), "fake", validLoginStart()); err != nil {
+		t.Fatalf("begin login: %v", err)
+	}
+	auth, err := svc.ExchangeLogin(context.Background(), "fake", validLoginExchange())
+	if err != nil {
+		t.Fatalf("exchange login: %v", err)
+	}
+	if auth.AccessToken == "" || auth.RefreshToken == "" || provider.completeCnt != 1 {
+		t.Fatalf("expected local session after provider completion: auth=%+v complete calls=%d", auth, provider.completeCnt)
+	}
+}
+
+func TestService_ExchangeLoginRejectsIdentityFromAnotherProvider(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(LoginCompleteInput) (ExternalIdentity, error) {
+		return ExternalIdentity{
+			Provider:      "another-provider",
+			Subject:       "subject-1",
+			Email:         "user@example.com",
+			EmailVerified: true,
+		}, nil
+	}
+	_, err := svc.ExchangeLogin(context.Background(), "fake", validLoginExchange())
+	if got := oauthErrorCode(t, err); got != OAuthFailed {
+		t.Fatalf("oauth code = %q, want %q", got, OAuthFailed)
+	}
+}
+
+func TestService_ExchangeLoginMapsProviderErrorsToControlledCodes(t *testing.T) {
+	tests := []struct {
+		name          string
+		providerError error
+		wantCode      OAuthErrorCode
+	}{
+		{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) {
+			provider, svc := validFakeProvider(t)
+			if _, err := svc.BeginLogin(context.Background(), "fake", validLoginStart()); err != nil {
+				t.Fatalf("begin login: %v", err)
+			}
+			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 {
+				t.Fatalf("oauth code = %q, want %q", got, tt.wantCode)
+			}
+		})
+	}
+}
+
+func TestService_ExchangeLoginRejectsMissingStatePKCEAndCode(t *testing.T) {
+	_, svc := validFakeProvider(t)
+	tests := []struct {
+		name string
+		in   LoginExchangeInput
+		want OAuthErrorCode
+	}{
+		{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) {
+			_, err := svc.ExchangeLogin(context.Background(), "fake", tt.in)
+			if got := oauthErrorCode(t, err); got != tt.want {
+				t.Fatalf("oauth code = %q, want %q", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestService_ExchangeLoginConsumesStateAndBindsThePKCEVerifier(t *testing.T) {
+	provider, svc := validFakeProvider(t)
+	if _, err := svc.BeginLogin(context.Background(), "fake", validLoginStart()); err != nil {
+		t.Fatalf("begin login: %v", err)
+	}
+	wrong := validLoginExchange()
+	wrong.CodeVerifier = testOAuthVerifier + "x"
+	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) != OAuthStateInvalid {
+		t.Fatalf("a rejected exchange must consume the one-time transaction: %v", err)
+	}
+	if provider.completeCnt != 0 {
+		t.Fatal("provider must not receive a wrong PKCE verifier")
+	}
+}
+
+func TestService_UnconfiguredProviderDoesNotBuildAURL(t *testing.T) {
+	svc := newTestServiceWithProviders(&fakeRepo{}, newFakeTokenStore())
+	start, err := svc.BeginLogin(context.Background(), "google", validLoginStart())
+	if start != nil {
+		t.Fatalf("unconfigured provider returned a login start: %+v", start)
+	}
+	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 != OAuthProviderUnavailable {
+		t.Fatalf("exchange oauth code = %q, want %q", got, OAuthProviderUnavailable)
+	}
+}
+
+func TestProviderRegistry_UsesProviderNameAsTheOnlyLookupKey(t *testing.T) {
+	provider := &fakeLoginProvider{name: "fake"}
+	registry := NewProviderRegistry(provider)
+	if got, ok := registry.Lookup("fake"); !ok || got != provider {
+		t.Fatalf("registry lookup = (%v, %v), want fake provider", got, ok)
+	}
+	if _, ok := registry.Lookup("google"); ok {
+		t.Fatal("registry must not synthesize an unconfigured provider")
+	}
+}
+
+func TestService_BeginLoginRejectsEmptyProviderAuthorizationURL(t *testing.T) {
+	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 != 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 _ LoginProvider = (*fakeLoginProvider)(nil)

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

@@ -0,0 +1,82 @@
+package application
+
+import (
+	"context"
+	"errors"
+	"fmt"
+
+	"{{goModule}}/internal/app/user/domain"
+	"{{goModule}}/internal/app/user/ports"
+
+	"github.com/google/uuid"
+)
+
+type Recovery struct {
+	repo   ports.UserRepository
+	tokens ports.RecoveryTokenStore
+	hasher PasswordHasher
+}
+
+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 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 {
+		return uuid.Nil, fmt.Errorf("hash password: %w", err)
+	}
+
+	var userID uuid.UUID
+	err = r.tokens.WithTransaction(ctx, func(txctx context.Context) error {
+		id, ok, err := r.tokens.ConsumePasswordResetToken(txctx, tokenHash)
+		if err != nil {
+			return fmt.Errorf("consume password reset token: %w", err)
+		}
+		if !ok {
+			return domain.ErrInvalidToken
+		}
+
+		identity, err := r.repo.FindIdentity(txctx, id, domain.ProviderLocal)
+		if err != nil {
+			return fmt.Errorf("find local identity: %w", err)
+		}
+		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)
+		}
+		userID = id
+		return nil
+	})
+	return userID, err
+}
+
+func (r *Recovery) VerifyEmail(ctx context.Context, tokenHash string) (uuid.UUID, error) {
+	var userID uuid.UUID
+	err := r.tokens.WithTransaction(ctx, func(txctx context.Context) error {
+		id, ok, err := r.tokens.ConsumeEmailVerifyToken(txctx, tokenHash)
+		if err != nil {
+			return fmt.Errorf("consume email verification token: %w", err)
+		}
+		if !ok {
+			return domain.ErrInvalidToken
+		}
+
+		user, err := r.repo.FindByID(txctx, id)
+		if err != nil {
+			return fmt.Errorf("find user for email verification: %w", err)
+		}
+		user.EmailVerified = true
+		if err := r.repo.UpdateUser(txctx, user); err != nil {
+			return fmt.Errorf("mark email verified: %w", err)
+		}
+		userID = id
+		return nil
+	})
+	return userID, err
+}