@nakedev/go-scaffold 0.1.3 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nakedev/go-scaffold",
-  "version": "0.1.3",
+  "version": "0.3.0",
   "description": "Scaffold Gin + GORM + Postgres Go backend projects with a consistent domain-module standard",
   "repository": {
     "type": "git",
@@ -15,11 +15,16 @@
     "bin"
   ],
   "type": "commonjs",
+  "packageManager": "pnpm@11.0.7",
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
-    "test": "node scripts/smoke-test.mjs",
+    "test": "pnpm run test:unit && pnpm run test:integration && pnpm run test:smoke",
+    "test:unit": "node --test tests/unit/*.test.mjs",
+    "test:integration": "node --test tests/integration/*.test.mjs",
+    "test:smoke": "node scripts/smoke-test.mjs",
     "verify": "pnpm run build && pnpm run test",
+    "prepack": "rm -rf dist && pnpm run build",
     "prepublishOnly": "pnpm run verify"
   },
   "keywords": [
@@ -40,14 +45,16 @@
     "commander": "^15.0.0",
     "fs-extra": "^11.3.0",
     "handlebars": "^4.7.8",
-    "picocolors": "^1.1.1"
+    "picocolors": "^1.1.1",
+    "pluralize": "^8.0.0"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",
     "@types/node": "^24.0.0",
+    "@types/pluralize": "^0.0.33",
     "typescript": "^5.7.0"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22.13"
   }
 }

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

@@ -21,6 +21,13 @@ func errEmailTaken() *apperror.AppError {
 // errInvalidCredentials is returned for both "no such user" and "wrong
 // password" — a single generic message so a login attempt can't be used to
 // enumerate which emails have accounts.
+// errTooManyAttempts is the account-level lockout, distinct from the per-IP
+// RATE_LIMITED the middleware returns: this one follows the account wherever
+// the attempts come from.
+func errTooManyAttempts() *apperror.AppError {
+	return apperror.New(http.StatusTooManyRequests, "AUTH_TOO_MANY_ATTEMPTS", "too many failed attempts — try again later")
+}
+
 func errInvalidCredentials() *apperror.AppError {
 	return apperror.New(http.StatusUnauthorized, "AUTH_INVALID_CREDENTIALS", "invalid email or password")
 }

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

@@ -2,6 +2,7 @@ package user
 
 import (
 	"net/http"
+	"strings"
 	"time"
 
 	"{{goModule}}/internal/shared/httpx"
@@ -10,19 +11,26 @@ import (
 
 	"github.com/gin-gonic/gin"
 	"github.com/google/uuid"
-	"github.com/redis/go-redis/v9"
 )
 
-const refreshCookieName = "refresh_token"
+const (
+	refreshCookieName = "refresh_token"
+	// oauthStateCookieName holds the nonce that binds a Google login to the
+	// browser that started it — see Service.GoogleLoginURL.
+	oauthStateCookieName = "oauth_state"
+)
 
 // go-scaffold:user-handler-consts
 
 type Handler struct {
-	svc          *Service
-	jwtSecret    string
-	refreshTTL   time.Duration
-	cookieSecure bool
-	rdb          *redis.Client
+	svc            *Service
+	jwtSecret      string
+	refreshTTL     time.Duration
+	cookieSecure   bool
+	cookieSameSite string
+	// limiter, not a *redis.Client: which backing store counts the requests is
+	// decided by `add auth --store`, and this file must not care.
+	limiter middleware.Limiter
 	// go-scaffold:user-handler-fields
 }
 
@@ -31,15 +39,17 @@ func NewHandler(
 	jwtSecret string,
 	refreshTTL time.Duration,
 	cookieSecure bool,
-	rdb *redis.Client,
+	cookieSameSite string,
+	limiter middleware.Limiter,
 	// go-scaffold:user-handler-params
 ) *Handler {
 	return &Handler{
-		svc:          svc,
-		jwtSecret:    jwtSecret,
-		refreshTTL:   refreshTTL,
-		cookieSecure: cookieSecure,
-		rdb:          rdb,
+		svc:            svc,
+		jwtSecret:      jwtSecret,
+		refreshTTL:     refreshTTL,
+		cookieSecure:   cookieSecure,
+		cookieSameSite: cookieSameSite,
+		limiter:        limiter,
 		// go-scaffold:user-handler-init
 	}
 }
@@ -52,12 +62,12 @@ func (h *Handler) Register(rg gin.IRouter) {
 	// doesn't spend another's budget. refresh/logout/google aren't limited:
 	// refresh/logout are gated by possessing a valid cookie already, and the
 	// Google flow's abuse surface lives on Google's side, not ours.
-	loginLimit := middleware.RateLimit(h.rdb, "login", 10, time.Minute)
-	registerLimit := middleware.RateLimit(h.rdb, "register", 5, time.Minute)
-	forgotPasswordLimit := middleware.RateLimit(h.rdb, "forgot-password", 5, time.Minute)
-	resetPasswordLimit := middleware.RateLimit(h.rdb, "reset-password", 10, time.Minute)
-	verifyEmailLimit := middleware.RateLimit(h.rdb, "verify-email", 10, time.Minute)
-	resendVerificationLimit := middleware.RateLimit(h.rdb, "resend-verification", 5, time.Minute)
+	loginLimit := middleware.RateLimit(h.limiter, "login", 10, time.Minute)
+	registerLimit := middleware.RateLimit(h.limiter, "register", 5, time.Minute)
+	forgotPasswordLimit := middleware.RateLimit(h.limiter, "forgot-password", 5, time.Minute)
+	resetPasswordLimit := middleware.RateLimit(h.limiter, "reset-password", 10, time.Minute)
+	verifyEmailLimit := middleware.RateLimit(h.limiter, "verify-email", 10, time.Minute)
+	resendVerificationLimit := middleware.RateLimit(h.limiter, "resend-verification", 5, time.Minute)
 
 	authGroup := rg.Group("/auth")
 	authGroup.POST("/register", registerLimit, h.register)
@@ -194,16 +204,26 @@ func (h *Handler) logoutAll(c *gin.Context) {
 }
 
 func (h *Handler) googleLogin(c *gin.Context) {
-	url, err := h.svc.GoogleLoginURL()
+	url, nonce, err := h.svc.GoogleLoginURL()
 	if err != nil {
 		c.Error(err)
 		return
 	}
+	// Lax, not Strict, and deliberately not h.cookieSameSite: the callback
+	// arrives as a top-level navigation from Google, i.e. cross-site, and a
+	// Strict cookie is not sent on one — the flow would fail every time.
+	c.SetSameSite(http.SameSiteLaxMode)
+	c.SetCookie(oauthStateCookieName, nonce, int(oauthStateTTL.Seconds()), "/", "", h.cookieSecure, true)
 	c.Redirect(http.StatusFound, url)
 }
 
 func (h *Handler) googleCallback(c *gin.Context) {
-	auth, err := h.svc.GoogleCallback(c.Request.Context(), c.Query("code"), c.Query("state"))
+	nonce, _ := c.Cookie(oauthStateCookieName)
+	// One shot, whatever happens next.
+	c.SetSameSite(http.SameSiteLaxMode)
+	c.SetCookie(oauthStateCookieName, "", -1, "/", "", h.cookieSecure, true)
+
+	auth, err := h.svc.GoogleCallback(c.Request.Context(), c.Query("code"), c.Query("state"), nonce)
 	if err != nil {
 		c.Error(err)
 		return
@@ -225,11 +245,32 @@ func (h *Handler) me(c *gin.Context) {
 // go-scaffold:user-handler-funcs
 
 func (h *Handler) setRefreshCookie(c *gin.Context, token string) {
-	c.SetSameSite(http.SameSiteStrictMode)
+	c.SetSameSite(sameSiteFrom(h.cookieSameSite))
 	c.SetCookie(refreshCookieName, token, int(h.refreshTTL.Seconds()), "/", "", h.cookieSecure, true)
 }
 
 func (h *Handler) clearRefreshCookie(c *gin.Context) {
-	c.SetSameSite(http.SameSiteStrictMode)
+	c.SetSameSite(sameSiteFrom(h.cookieSameSite))
 	c.SetCookie(refreshCookieName, "", -1, "/", "", h.cookieSecure, true)
 }
+
+// sameSiteFrom maps COOKIE_SAMESITE onto the http constant, defaulting to the
+// strictest option for anything it doesn't recognise.
+//
+// "strict" is right while the frontend and this API are the same site
+// (localhost:3000 -> localhost:8080 is, and so is app.example.com ->
+// api.example.com). A frontend on a genuinely different site — the usual
+// vercel.app-plus-own-API-domain split — needs "none", because the browser
+// will not attach a Strict or Lax cookie to the fetch that calls
+// /auth/refresh: sessions then die at every access-token expiry with no
+// error anywhere to explain it. "none" requires COOKIE_SECURE=true.
+func sameSiteFrom(mode string) http.SameSite {
+	switch strings.ToLower(mode) {
+	case "none":
+		return http.SameSiteNoneMode
+	case "lax":
+		return http.SameSiteLaxMode
+	default:
+		return http.SameSiteStrictMode
+	}
+}

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

@@ -3,6 +3,7 @@ package user
 import (
 	"crypto/rand"
 	"crypto/sha256"
+	"crypto/subtle"
 	"encoding/hex"
 	"time"
 
@@ -22,6 +23,8 @@ const (
 // presented where the other is expected.
 type accessClaims struct {
 	Typ string `json:"typ"`
+	// Nonce is only set on the OAuth state token — see issueOAuthState.
+	Nonce string `json:"nonce,omitempty"`
 	// go-scaffold:jwt-claims
 	jwt.RegisteredClaims
 }
@@ -42,21 +45,37 @@ func (s *Service) issueAccessToken(
 	return jwt.NewWithClaims(jwt.SigningMethodHS256, claims).SignedString([]byte(s.jwtSecret))
 }
 
-// issueOAuthState / verifyOAuthState round-trip a short-lived, stateless CSRF
-// token through Google's own redirect — no server-side row needed, the JWT's
-// signature + short TTL is the whole protection.
-func (s *Service) issueOAuthState() (string, error) {
+// issueOAuthState / verifyOAuthState round-trip a short-lived CSRF token
+// through Google's own redirect. The signature and TTL are not the whole
+// protection: a signed-but-unbound state is one anyone can fetch from
+// GET /auth/google/login and then replay in a victim's browser, which is
+// exactly the login-CSRF the state parameter exists to stop. So the token
+// carries a nonce that the handler also drops in a short-lived httpOnly
+// cookie, and the callback only proceeds when the two agree — the state is
+// then usable in one browser only, the one that started the flow.
+//
+// Returns the state and the nonce to put in that cookie.
+func (s *Service) issueOAuthState() (string, string, error) {
+	nonce, err := randomToken()
+	if err != nil {
+		return "", "", err
+	}
 	claims := accessClaims{
-		Typ: tokenTypeOAuthState,
+		Typ:   tokenTypeOAuthState,
+		Nonce: nonce,
 		RegisteredClaims: jwt.RegisteredClaims{
 			IssuedAt:  jwt.NewNumericDate(time.Now()),
 			ExpiresAt: jwt.NewNumericDate(time.Now().Add(oauthStateTTL)),
 		},
 	}
-	return jwt.NewWithClaims(jwt.SigningMethodHS256, claims).SignedString([]byte(s.jwtSecret))
+	state, err := jwt.NewWithClaims(jwt.SigningMethodHS256, claims).SignedString([]byte(s.jwtSecret))
+	if err != nil {
+		return "", "", err
+	}
+	return state, nonce, nil
 }
 
-func (s *Service) verifyOAuthState(raw string) error {
+func (s *Service) verifyOAuthState(raw, nonce string) error {
 	var claims accessClaims
 	_, err := jwt.ParseWithClaims(raw, &claims, func(*jwt.Token) (any, error) {
 		return []byte(s.jwtSecret), nil
@@ -64,6 +83,11 @@ func (s *Service) verifyOAuthState(raw string) error {
 	if err != nil || claims.Typ != tokenTypeOAuthState {
 		return errInvalidToken()
 	}
+	// A missing cookie is a mismatch, not a pass — otherwise stripping the
+	// cookie is all it takes to get the old, unbound behavior back.
+	if nonce == "" || subtle.ConstantTimeCompare([]byte(claims.Nonce), []byte(nonce)) != 1 {
+		return errInvalidToken()
+	}
 	return nil
 }
 

package/templates/add/auth/internal/app/user/model/authtoken.go.hbs

@@ -0,0 +1,39 @@
+package model
+
+import (
+	"time"
+
+	"github.com/google/uuid"
+)
+
+// AuthToken is one short-lived token — the Postgres equivalent of the keys the
+// Redis store would hold. Only the SHA-256 hash of the raw token is stored, so
+// a database dump never yields a usable token.
+//
+// `Kind` mirrors the Redis key prefixes one-for-one, deliberately:
+//
+//	refresh       an active refresh token
+//	refresh_used  a tombstone left by rotation, so replaying a rotated-out
+//	              token is detectable as reuse rather than merely unknown
+//	pwreset       password reset, consumed once
+//	emailverify   email verification, consumed once
+//
+// Keeping the tombstone a separate row (rather than a used_at column on the
+// refresh row) is what preserves logout's semantics: logout deletes the row
+// outright and leaves no tombstone, so someone replaying a logged-out token
+// gets a plain rejection instead of tripping reuse detection and nuking every
+// session the user has.
+//
+// No foreign key to users on purpose: GORM's AutoMigrate (dev) wouldn't create
+// one from these tags, and a constraint that exists in production but not in
+// development is the exact mismatch that stops the app booting. A token whose
+// user is gone simply fails the lookup that follows.
+type AuthToken struct {
+	TokenHash string    `gorm:"primaryKey;type:text"`
+	UserID    uuid.UUID `gorm:"type:uuid;not null;index:idx_auth_tokens_user_kind,priority:1"`
+	Kind      string    `gorm:"type:varchar(20);not null;index:idx_auth_tokens_user_kind,priority:2"`
+	ExpiresAt time.Time `gorm:"not null;index:idx_auth_tokens_expires_at"`
+	CreatedAt time.Time
+}
+
+func (AuthToken) TableName() string { return "user_svc.auth_tokens" }

package/templates/add/auth/internal/app/user/model/identity.go.hbs

@@ -26,3 +26,6 @@ type Identity struct {
 	CreatedAt    time.Time `json:"created_at"`
 	UpdatedAt    time.Time `json:"updated_at"`
 }
+
+// TableName — see User.TableName; same schema, same reasoning.
+func (Identity) TableName() string { return "user_svc.identities" }

package/templates/add/auth/internal/app/user/model/loginthrottle.go.hbs

@@ -0,0 +1,26 @@
+package model
+
+import "time"
+
+// LoginThrottle is the failed-attempt counter that makes lockout survive a
+// deploy and mean the same thing on every replica. It is not the rate limiter
+// — that one counts requests per IP and is allowed to be approximate. This
+// counts failures per account, and per OWASP that is the control that actually
+// stops credential stuffing: an attacker with a proxy pool keeps per-IP volume
+// under any threshold you set, but they cannot spread attempts against one
+// account across accounts.
+//
+// EmailHash, not the address: the counter has to be keyed on what the caller
+// typed whether or not an account exists — otherwise "did this get throttled"
+// answers "does this account exist" — and hashing means this table never
+// becomes a directory of who has signed up.
+type LoginThrottle struct {
+	EmailHash string `gorm:"primaryKey;type:text"`
+	Failures  int    `gorm:"not null;default:0"`
+	// nil until the free attempts are spent; afterwards it moves further out
+	// with each failure.
+	LockedUntil *time.Time
+	UpdatedAt   time.Time
+}
+
+func (LoginThrottle) TableName() string { return "user_svc.login_throttle" }

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

@@ -12,7 +12,10 @@ import (
 // resolving to one account.
 type User struct {
 	ID            uuid.UUID `json:"id" gorm:"type:uuid;primaryKey"`
-	Email         string    `json:"email" gorm:"uniqueIndex;not null"`
+	// index named explicitly, and named the same in create_users.up.sql: an
+	// anonymous `uniqueIndex` makes GORM invent one, and AutoMigrate then
+	// tries to DROP the differently-named constraint the migration created.
+	Email         string    `json:"email" gorm:"uniqueIndex:idx_users_email;not null"`
 	Name          string    `json:"name"`
 	AvatarURL     string    `json:"avatar_url"`
 	EmailVerified bool      `json:"email_verified"`
@@ -20,3 +23,8 @@ type User struct {
 	CreatedAt time.Time `json:"created_at"`
 	UpdatedAt time.Time `json:"updated_at"`
 }
+
+// TableName pins this to user_svc rather than GORM's default inflection
+// ("users", schema-less) — every domain gets its own schema, see
+// docs/architect/patterns.md.
+func (User) TableName() string { return "user_svc.users" }

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

@@ -2,8 +2,11 @@ package user
 
 import (
 	"context"
+	"errors"
+	"time"
 
 	"{{goModule}}/internal/app/user/model"
+	"{{goModule}}/internal/shared/tx"
 
 	"github.com/google/uuid"
 	"gorm.io/gorm"
@@ -19,7 +22,7 @@ func NewRepository(db *gorm.DB) *Repository {
 
 func (r *Repository) FindByEmail(ctx context.Context, email string) (*model.User, error) {
 	var u model.User
-	if err := r.db.WithContext(ctx).First(&u, "email = ?", email).Error; err != nil {
+	if err := tx.From(ctx, r.db).WithContext(ctx).First(&u, "email = ?", email).Error; err != nil {
 		return nil, err
 	}
 	return &u, nil
@@ -27,25 +30,25 @@ func (r *Repository) FindByEmail(ctx context.Context, email string) (*model.User
 
 func (r *Repository) FindByID(ctx context.Context, id uuid.UUID) (*model.User, error) {
 	var u model.User
-	if err := r.db.WithContext(ctx).First(&u, "id = ?", id).Error; err != nil {
+	if err := tx.From(ctx, r.db).WithContext(ctx).First(&u, "id = ?", id).Error; err != nil {
 		return nil, err
 	}
 	return &u, nil
 }
 
 func (r *Repository) UpdateUser(ctx context.Context, u *model.User) error {
-	return r.db.WithContext(ctx).Save(u).Error
+	return tx.From(ctx, r.db).WithContext(ctx).Save(u).Error
 }
 
 func (r *Repository) FindAll(ctx context.Context, limit, offset int) ([]model.User, error) {
 	var items []model.User
-	err := r.db.WithContext(ctx).Order("created_at desc").Limit(limit).Offset(offset).Find(&items).Error
+	err := tx.From(ctx, r.db).WithContext(ctx).Order("created_at desc").Limit(limit).Offset(offset).Find(&items).Error
 	return items, err
 }
 
 func (r *Repository) FindIdentity(ctx context.Context, userID uuid.UUID, provider model.Provider) (*model.Identity, error) {
 	var i model.Identity
-	if err := r.db.WithContext(ctx).First(&i, "user_id = ? AND provider = ?", userID, provider).Error; err != nil {
+	if err := tx.From(ctx, r.db).WithContext(ctx).First(&i, "user_id = ? AND provider = ?", userID, provider).Error; err != nil {
 		return nil, err
 	}
 	return &i, nil
@@ -53,7 +56,7 @@ func (r *Repository) FindIdentity(ctx context.Context, userID uuid.UUID, provide
 
 func (r *Repository) FindIdentityByProviderUID(ctx context.Context, provider model.Provider, providerUID string) (*model.Identity, error) {
 	var i model.Identity
-	if err := r.db.WithContext(ctx).First(&i, "provider = ? AND provider_uid = ?", provider, providerUID).Error; err != nil {
+	if err := tx.From(ctx, r.db).WithContext(ctx).First(&i, "provider = ? AND provider_uid = ?", provider, providerUID).Error; err != nil {
 		return nil, err
 	}
 	return &i, nil
@@ -63,22 +66,72 @@ func (r *Repository) FindIdentityByProviderUID(ctx context.Context, provider mod
 // Google linking onto an account that registered with a password first) —
 // see CreateUserWithIdentity for the "brand new user" case.
 func (r *Repository) CreateIdentity(ctx context.Context, i *model.Identity) error {
-	return r.db.WithContext(ctx).Create(i).Error
+	return tx.From(ctx, r.db).WithContext(ctx).Create(i).Error
 }
 
 func (r *Repository) UpdateIdentity(ctx context.Context, i *model.Identity) error {
-	return r.db.WithContext(ctx).Save(i).Error
+	return tx.From(ctx, r.db).WithContext(ctx).Save(i).Error
 }
 
 // CreateUserWithIdentity inserts the profile and its first login method in
 // one transaction — a user with no identity at all can't log in any way, so
 // the two rows always exist together or not at all.
 func (r *Repository) CreateUserWithIdentity(ctx context.Context, u *model.User, i *model.Identity) error {
-	return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
-		if err := tx.Create(u).Error; err != nil {
+	return tx.From(ctx, r.db).WithContext(ctx).Transaction(func(t *gorm.DB) error {
+		if err := t.Create(u).Error; err != nil {
 			return err
 		}
 		i.UserID = u.ID
-		return tx.Create(i).Error
+		return t.Create(i).Error
 	})
 }
+
+// --- failed-login throttle -------------------------------------------------
+//
+// Keyed on a caller-supplied hash rather than a user id, because the counter
+// has to work for addresses that have no account — see model.LoginThrottle.
+
+// LoginLockedUntil reports when this key stops being locked out — zero time
+// when it isn't. Read on every login attempt, so it stays a primary-key hit.
+func (r *Repository) LoginLockedUntil(ctx context.Context, key string) (time.Time, error) {
+	var row model.LoginThrottle
+	err := tx.From(ctx, r.db).WithContext(ctx).Where("email_hash = ?", key).Take(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return time.Time{}, nil
+	}
+	if err != nil || row.LockedUntil == nil {
+		return time.Time{}, err
+	}
+	return *row.LockedUntil, nil
+}
+
+// RecordLoginFailure bumps the counter and pushes the lock further out,
+// doubling each time past freeAttempts and never exceeding maxLock.
+//
+// One statement, so two attempts racing cannot both read the same count and
+// write the same lock — which would let an attacker keep the backoff pinned at
+// its first step by running attempts in parallel. Computing the interval in
+// SQL is what buys that; a read-then-write in Go would need a transaction and
+// a row lock to be equally safe.
+func (r *Repository) RecordLoginFailure(ctx context.Context, key string, freeAttempts int, maxLock time.Duration) error {
+	return tx.From(ctx, r.db).WithContext(ctx).Exec(`
+		INSERT INTO user_svc.login_throttle AS t (email_hash, failures, locked_until, updated_at)
+		VALUES (?, 1, NULL, now())
+		ON CONFLICT (email_hash) DO UPDATE SET
+			failures = t.failures + 1,
+			locked_until = CASE
+				WHEN t.failures + 1 <= ? THEN NULL
+				ELSE now() + make_interval(secs => least(power(2, t.failures + 1 - ?), ?))
+			END,
+			updated_at = now()`,
+		key, freeAttempts, freeAttempts, maxLock.Seconds()).Error
+}
+
+// ClearLoginFailures drops the row on a successful login, so someone who
+// mistypes twice and then gets in starts clean rather than creeping toward a
+// lockout over weeks.
+func (r *Repository) ClearLoginFailures(ctx context.Context, key string) error {
+	return tx.From(ctx, r.db).WithContext(ctx).
+		Where("email_hash = ?", key).
+		Delete(&model.LoginThrottle{}).Error
+}