@nakedev/go-scaffold 0.4.0 → 0.5.0

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

@@ -0,0 +1,196 @@
+package redisadapter
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"os"
+	"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")
+	if url == "" {
+		if os.Getenv("REQUIRE_TEST_REDIS") == "true" {
+			t.Fatal("TEST_REDIS_URL is required when REQUIRE_TEST_REDIS=true")
+		}
+		t.Skip("token-store integration test skipped: set TEST_REDIS_URL to a Redis instance")
+	}
+
+	options, err := redis.ParseURL(url)
+	if err != nil {
+		if os.Getenv("REQUIRE_TEST_REDIS") == "true" {
+			t.Fatalf("parse required Redis URL: %v", err)
+		}
+		t.Skipf("token-store integration test skipped: %v", err)
+	}
+	client := redis.NewClient(options)
+	if err := client.Ping(context.Background()).Err(); err != nil {
+		_ = client.Close()
+		if os.Getenv("REQUIRE_TEST_REDIS") == "true" {
+			t.Fatalf("ping required Redis: %v", err)
+		}
+		t.Skipf("token-store integration test skipped: %v", err)
+	}
+	t.Cleanup(func() { _ = client.Close() })
+	return client
+}
+
+func TestRefreshTokenRecord_JSONUsesLuaFieldNames(t *testing.T) {
+	raw, err := json.Marshal(testRefreshTokenRecord(uuid.New()))
+	if err != nil {
+		t.Fatalf("marshal refresh token record: %v", err)
+	}
+
+	var payload map[string]json.RawMessage
+	if err := json.Unmarshal(raw, &payload); err != nil {
+		t.Fatalf("decode refresh token record: %v", err)
+	}
+	if _, ok := payload["user_id"]; !ok {
+		t.Fatalf("Redis refresh payload must contain user_id, got %s", raw)
+	}
+	if _, ok := payload["UserID"]; ok {
+		t.Fatalf("Redis refresh payload must not contain Go field name UserID: %s", raw)
+	}
+}
+
+func TestRedisTokenStore_ConsumeRefreshToken_ConcurrentRealRedis(t *testing.T) {
+	client := redisClientForTest(t)
+	store := NewRedisTokenStore(client, nil)
+	ctx := context.Background()
+	userID := uuid.New()
+	hash := "real-redis-refresh-" + uuid.NewString()
+	if err := store.SetRefreshToken(ctx, hash, testRefreshTokenRecord(userID)); err != nil {
+		t.Fatalf("seed refresh token: %v", err)
+	}
+	t.Cleanup(func() { _ = store.RevokeAllRefreshTokens(ctx, userID) })
+
+	const callers = 32
+	start := make(chan struct{})
+	results := make(chan struct {
+		token ports.RefreshTokenRecord
+		ok    bool
+		err   error
+	}, callers)
+	for i := 0; i < callers; i++ {
+		go func() {
+			<-start
+			token, ok, err := store.ConsumeRefreshToken(ctx, hash)
+			results <- struct {
+				token ports.RefreshTokenRecord
+				ok    bool
+				err   error
+			}{token: token, ok: ok, err: err}
+		}()
+	}
+	close(start)
+
+	winners := 0
+	for i := 0; i < callers; i++ {
+		got := <-results
+		if got.err != nil {
+			t.Fatalf("concurrent consume: %v", got.err)
+		}
+		if got.ok {
+			winners++
+			if got.token.UserID != userID {
+				t.Fatalf("winner returned user %s, want %s", got.token.UserID, userID)
+			}
+		}
+	}
+	if winners != 1 {
+		t.Fatalf("expected exactly one real-Redis refresh winner, got %d", winners)
+	}
+}
+
+func TestRedisTokenStore_ConsumeRefreshToken_MalformedRecordDoesNotDelete(t *testing.T) {
+	client := redisClientForTest(t)
+	store := NewRedisTokenStore(client, nil)
+	ctx := context.Background()
+	hash := "real-redis-malformed-" + uuid.NewString()
+	key := refreshKeyPrefix + hash
+	if err := client.Set(ctx, key, "not-json", time.Minute).Err(); err != nil {
+		t.Fatalf("seed malformed refresh token: %v", err)
+	}
+	t.Cleanup(func() { _ = client.Del(ctx, key).Err() })
+
+	if _, ok, err := store.ConsumeRefreshToken(ctx, hash); err == nil || ok {
+		t.Fatalf("malformed refresh token must fail without being consumed, ok=%t err=%v", ok, err)
+	}
+	exists, err := client.Exists(ctx, key).Result()
+	if err != nil {
+		t.Fatalf("check malformed refresh token: %v", err)
+	}
+	if exists != 1 {
+		t.Fatal("malformed refresh token was deleted before validation")
+	}
+}
+
+func TestRedisTokenStore_RevokeAllRefreshTokens_IsAtomicWithSet(t *testing.T) {
+	client := redisClientForTest(t)
+	store := NewRedisTokenStore(client, nil)
+	ctx := context.Background()
+	userID := uuid.New()
+	setKey := refreshUserKeyPrefix + userID.String()
+	t.Cleanup(func() { _ = store.RevokeAllRefreshTokens(ctx, userID) })
+
+	// An invariant is stronger than checking the final session count: an
+	// active token must always have a member in the user's set. The old
+	// SMEMBERS -> pipeline implementation could leave exactly that split when
+	// SetRefreshToken landed between the two phases.
+	for i := 0; i < 128; i++ {
+		existingHash := fmt.Sprintf("real-redis-existing-%s-%d", userID, i)
+		newHash := fmt.Sprintf("real-redis-racing-%s-%d", userID, i)
+		if err := store.SetRefreshToken(ctx, existingHash, testRefreshTokenRecord(userID)); err != nil {
+			t.Fatalf("seed existing token: %v", err)
+		}
+
+		start := make(chan struct{})
+		errs := make(chan error, 2)
+		go func() {
+			<-start
+			errs <- store.RevokeAllRefreshTokens(ctx, userID)
+		}()
+		go func() {
+			<-start
+			errs <- store.SetRefreshToken(ctx, newHash, testRefreshTokenRecord(userID))
+		}()
+		close(start)
+		for j := 0; j < 2; j++ {
+			if err := <-errs; err != nil {
+				t.Fatalf("concurrent revoke/set: %v", err)
+			}
+		}
+
+		_, active, err := store.GetRefreshToken(ctx, newHash)
+		if err != nil {
+			t.Fatalf("read racing token: %v", err)
+		}
+		member, err := client.SIsMember(ctx, setKey, newHash).Result()
+		if err != nil {
+			t.Fatalf("read session set: %v", err)
+		}
+		if active != member {
+			t.Fatalf("inconsistent Redis session state at round %d: active=%t set_member=%t", i, active, member)
+		}
+		if err := store.RevokeAllRefreshTokens(ctx, userID); err != nil {
+			t.Fatalf("cleanup round %d: %v", i, 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

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

@@ -0,0 +1,62 @@
+package application
+
+import (
+	"fmt"
+
+	"{{goModule}}/internal/app/user/domain"
+)
+
+// Use-case errors carry a stable business code and a domain sentinel. The
+// inbound adapter decides how those errors map to HTTP; application code does
+// not know status codes or response envelopes.
+func errNotFound() error {
+	return domain.Rule("USER_NOT_FOUND", "user not found", domain.ErrNotFound)
+}
+
+func errEmailTaken() error {
+	return domain.Rule("USER_EMAIL_TAKEN", "email already registered", domain.ErrEmailTaken)
+}
+
+func errTooManyAttempts() error {
+	return domain.Rule("AUTH_TOO_MANY_ATTEMPTS", "too many failed attempts - try again later", domain.ErrTooManyAttempts)
+}
+
+func errInvalidCredentials() error {
+	return domain.Rule("AUTH_INVALID_CREDENTIALS", "invalid email or password", domain.ErrInvalidCredential)
+}
+
+func errInvalidToken() error {
+	return domain.Rule("AUTH_INVALID_TOKEN", "invalid or expired token", domain.ErrInvalidToken)
+}
+
+func errAlreadyVerified() error {
+	return domain.Rule("AUTH_ALREADY_VERIFIED", "email is already verified", domain.ErrAlreadyVerified)
+}
+
+func errMFAUnavailable() error {
+	return domain.Rule("AUTH_MFA_UNAVAILABLE", "multi-factor authentication is not enabled", domain.ErrMFAUnavailable)
+}
+
+func errMFAInvalid() error {
+	return domain.Rule("AUTH_MFA_INVALID", "invalid or expired multi-factor authentication code", domain.ErrMFAInvalid)
+}
+
+func errMFAAlreadyEnabled() error {
+	return domain.Rule("AUTH_MFA_ALREADY_ENABLED", "multi-factor authentication is already enabled", domain.ErrMFAAlreadyEnabled)
+}
+
+func errMFANotEnrolled() error {
+	return domain.Rule("AUTH_MFA_NOT_ENROLLED", "multi-factor authentication is not enabled for this user", domain.ErrMFANotEnrolled)
+}
+
+func errMFASetupRequired() error {
+	return domain.Rule("AUTH_MFA_SETUP_REQUIRED", "complete multi-factor authentication setup first", domain.ErrMFASetupRequired)
+}
+
+func errMFAConfig() error {
+	return fmt.Errorf("multi-factor authentication encryption key is invalid")
+}
+
+func errUnknownRole() error {
+	return domain.Rule("USER_UNKNOWN_ROLE", "unknown role code", domain.ErrUnknownRole)
+}

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

@@ -0,0 +1,198 @@
+package application
+
+import (
+	"context"
+	"crypto/sha256"
+	"crypto/subtle"
+	"encoding/base64"
+	"errors"
+	"fmt"
+	"strings"
+	"time"
+
+	"{{goModule}}/internal/app/user/domain"
+	"{{goModule}}/internal/shared/id"
+)
+
+// BeginLogin accepts the browser client's state and S256 PKCE challenge and
+// asks the registered provider adapter to construct its authorization URL.
+// The server persists a hashed state transaction binding provider, challenge,
+// and OIDC nonce before the callback reaches ExchangeLogin.
+func (s *Service) BeginLogin(ctx context.Context, providerName string, in LoginStartInput) (*Authorization, error) {
+	provider, ok := s.providers.Lookup(providerName)
+	if !ok {
+		return nil, NewOAuthError(OAuthProviderUnavailable, fmt.Errorf("provider %q is not configured", providerName))
+	}
+	// OAuth values are opaque: validate their wire-safe shape without trimming
+	// or rewriting what the frontend and provider saw.
+	if !validOAuthValue(in.State) || !validPKCEChallenge(in.CodeChallenge) || in.CodeChallengeMethod != "S256" {
+		return nil, NewOAuthError(OAuthStateInvalid, fmt.Errorf("state and S256 code challenge are required"))
+	}
+	nonce, err := randomToken()
+	if err != nil {
+		return nil, NewOAuthError(OAuthProviderUnavailable, fmt.Errorf("create oauth transaction: %w", err))
+	}
+	in.Nonce = nonce
+	authorization, err := provider.Begin(ctx, in)
+	if err != nil {
+		return nil, mapProviderError(err)
+	}
+	if strings.TrimSpace(authorization.URL) == "" {
+		return nil, NewOAuthError(OAuthProviderUnavailable, fmt.Errorf("provider returned an empty authorization URL"))
+	}
+	clock := s.now
+	if clock == nil {
+		clock = time.Now
+	}
+	if err := s.oauthTransactions.SetLoginTransaction(ctx, hashToken(in.State), LoginTransaction{
+		Provider:      providerName,
+		CodeChallenge: in.CodeChallenge,
+		Nonce:         nonce,
+		ExpiresAt:     clock().Add(s.config.OAuthStateTTL),
+	}); err != nil {
+		return nil, NewOAuthError(OAuthProviderUnavailable, fmt.Errorf("store oauth transaction: %w", err))
+	}
+	return &authorization, nil
+}
+
+func (s *Service) ExchangeLogin(ctx context.Context, providerName string, in LoginExchangeInput) (*AuthResult, error) {
+	provider, ok := s.providers.Lookup(providerName)
+	if !ok {
+		return nil, NewOAuthError(OAuthProviderUnavailable, fmt.Errorf("provider %q is not configured", providerName))
+	}
+	if !validOAuthValue(in.State) || !validPKCEValue(in.CodeVerifier) {
+		return nil, NewOAuthError(OAuthStateInvalid, fmt.Errorf("state and code verifier are required"))
+	}
+	if !validOAuthValue(in.Code) {
+		return nil, NewOAuthError(OAuthFailed, fmt.Errorf("authorization code is missing"))
+	}
+
+	transaction, ok, err := s.oauthTransactions.ConsumeLoginTransaction(ctx, hashToken(in.State))
+	if err != nil {
+		return nil, NewOAuthError(OAuthProviderUnavailable, fmt.Errorf("consume oauth transaction: %w", err))
+	}
+	if !ok || transaction.Provider != providerName || !validPKCEVerifier(in.CodeVerifier, transaction.CodeChallenge) {
+		return nil, NewOAuthError(OAuthStateInvalid, fmt.Errorf("oauth state or PKCE verifier is invalid"))
+	}
+
+	identity, err := provider.Complete(ctx, LoginCompleteInput{Code: in.Code, CodeVerifier: in.CodeVerifier, Nonce: transaction.Nonce})
+	if err != nil {
+		return nil, mapProviderError(err)
+	}
+	if identity.Provider != providerName {
+		return nil, NewOAuthError(OAuthFailed, fmt.Errorf("provider identity name does not match the requested provider"))
+	}
+	u, err := s.findOrCreateExternalUser(ctx, identity)
+	if err != nil {
+		return nil, NewOAuthError(OAuthFailed, fmt.Errorf("resolve external identity: %w", err))
+	}
+	return s.completeLogin(ctx, u)
+}
+
+func validPKCEVerifier(verifier, challenge string) bool {
+	if !validPKCEValue(verifier) || !validPKCEValue(challenge) {
+		return false
+	}
+	computed := pkceChallenge(verifier)
+	return subtle.ConstantTimeCompare([]byte(computed), []byte(challenge)) == 1
+}
+
+// OAuth state and authorization codes use the RFC 6749 VSCHAR shape.
+func validOAuthValue(value string) bool {
+	if value == "" {
+		return false
+	}
+	for i := 0; i < len(value); i++ {
+		if value[i] < 0x20 || value[i] > 0x7e {
+			return false
+		}
+	}
+	return true
+}
+
+// RFC 7636 defines code_verifier/code_challenge as 43–128 unreserved ASCII
+// characters. S256 is the only method accepted by this scaffold.
+func validPKCEValue(value string) bool {
+	if len(value) < 43 || len(value) > 128 {
+		return false
+	}
+	for i := 0; i < len(value); i++ {
+		c := value[i]
+		switch {
+		case c >= 'A' && c <= 'Z':
+		case c >= 'a' && c <= 'z':
+		case c >= '0' && c <= '9':
+		case c == '-' || c == '.' || c == '_' || c == '~':
+		default:
+			return false
+		}
+	}
+	return true
+}
+
+func validPKCEChallenge(challenge string) bool {
+	return validPKCEValue(challenge)
+}
+
+func pkceChallenge(verifier string) string {
+	sum := sha256.Sum256([]byte(verifier))
+	return base64.RawURLEncoding.EncodeToString(sum[:])
+}
+
+func mapProviderError(err error) error {
+	var oauthErr *OAuthError
+	if errors.As(err, &oauthErr) {
+		return oauthErr
+	}
+	if IsProviderUnavailable(err) {
+		return NewOAuthError(OAuthProviderUnavailable, err)
+	}
+	return NewOAuthError(OAuthFailed, err)
+}
+
+// findOrCreateExternalUser is provider-neutral identity resolution. A stable
+// provider subject wins; only a verified external email may link to an
+// existing account.
+func (s *Service) findOrCreateExternalUser(ctx context.Context, info ExternalIdentity) (*domain.User, error) {
+	if strings.TrimSpace(info.Provider) == "" || strings.TrimSpace(info.Subject) == "" || strings.TrimSpace(info.Email) == "" {
+		return nil, fmt.Errorf("external identity is missing provider, subject, or email")
+	}
+	if len(info.Provider) > 20 {
+		return nil, fmt.Errorf("external identity provider name is too long")
+	}
+
+	provider := domain.Provider(info.Provider)
+	if ident, err := s.repo.FindIdentityByProviderUID(ctx, provider, info.Subject); err == nil {
+		user, findErr := s.repo.FindByID(ctx, ident.UserID)
+		if findErr != nil {
+			return nil, fmt.Errorf("find user for existing identity: %w", findErr)
+		}
+		return user, nil
+	} else if !errors.Is(err, domain.ErrNotFound) {
+		return nil, fmt.Errorf("find external identity: %w", err)
+	}
+
+	providerUID := info.Subject
+	email := normalizeEmail(info.Email)
+	if info.EmailVerified {
+		if u, err := s.repo.FindByEmail(ctx, email); err == nil {
+			ident := &domain.Identity{ID: id.New(), UserID: u.ID, Provider: provider, ProviderUID: &providerUID}
+			if err := s.repo.CreateIdentity(ctx, ident); err != nil {
+				return nil, fmt.Errorf("link external identity: %w", err)
+			}
+			return u, nil
+		} else if !errors.Is(err, domain.ErrNotFound) {
+			return nil, fmt.Errorf("find user by verified external email: %w", err)
+		}
+	}
+
+	u := &domain.User{ID: id.New(), Email: email, Name: info.Name, AvatarURL: info.AvatarURL, EmailVerified: info.EmailVerified, Role: domain.DefaultRole}
+	ident := &domain.Identity{ID: id.New(), Provider: provider, ProviderUID: &providerUID}
+	if err := s.repo.CreateUserWithIdentity(ctx, u, ident); err != nil {
+		if errors.Is(err, domain.ErrConflict) {
+			return nil, errEmailTaken()
+		}
+		return nil, fmt.Errorf("create external user: %w", err)
+	}
+	return u, nil
+}

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

@@ -0,0 +1,58 @@
+package application
+
+import (
+	"crypto/rand"
+	"crypto/sha256"
+	"encoding/hex"
+
+	"github.com/golang-jwt/jwt/v5"
+	"github.com/google/uuid"
+)
+
+const (
+	tokenTypeAccess = "access"
+)
+
+// accessClaims — see internal/shared/middleware/auth.go for why this struct
+// is duplicated there instead of imported.
+type accessClaims struct {
+	Typ  string `json:"typ"`
+	Role string `json:"role,omitempty"`
+	// go-scaffold:jwt-claims
+	jwt.RegisteredClaims
+}
+
+func (s *Service) issueAccessToken(
+	userID uuid.UUID,
+	role string,
+	// go-scaffold:issue-access-token-params
+) (string, error) {
+	now := s.clock()
+	claims := accessClaims{
+		Typ:  tokenTypeAccess,
+		Role: role,
+		// go-scaffold:jwt-claims-values
+		RegisteredClaims: jwt.RegisteredClaims{
+			Subject:   userID.String(),
+			IssuedAt:  jwt.NewNumericDate(now),
+			ExpiresAt: jwt.NewNumericDate(now.Add(s.config.JWTAccessTTL)),
+		},
+	}
+	return jwt.NewWithClaims(jwt.SigningMethodHS256, claims).SignedString([]byte(s.config.JWTSecret))
+}
+
+// randomToken generates an opaque refresh token — deliberately not a JWT:
+// nothing needs to read claims out of it, and only its hash (see hashToken)
+// is ever stored, so a leaked server-side store never exposes usable tokens.
+func randomToken() (string, error) {
+	b := make([]byte, 32)
+	if _, err := rand.Read(b); err != nil {
+		return "", err
+	}
+	return hex.EncodeToString(b), nil
+}
+
+func hashToken(raw string) string {
+	sum := sha256.Sum256([]byte(raw))
+	return hex.EncodeToString(sum[:])
+}