@nakedev/go-scaffold 0.1.2 → 0.1.4

package/templates/add/auth/cmd/seed/main.go.hbs

@@ -0,0 +1,76 @@
+package main
+
+import (
+	"context"
+	"flag"
+	"log/slog"
+	"os"
+
+	"{{goModule}}/internal/app/user"
+	"{{goModule}}/internal/platform/database"
+	"{{goModule}}/internal/shared/config"
+	// go-scaffold:seed-imports
+)
+
+// cmd/seed is a one-off operational task, like `migrate` — not part of the
+// API server's runtime, so it's a separate binary rather than a flag on
+// cmd/api. tokens/mailer are nil: EnsureUser never touches them (no login
+// or email flow runs during seeding).
+func main() {
+	withFixtures := flag.Bool("fixtures", false, "also seed sample dev users — do not use against a real environment")
+	flag.Parse()
+
+	cfg := config.Load()
+	logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
+
+	db, err := database.Open(cfg)
+	if err != nil {
+		logger.Error("open db", "error", err)
+		os.Exit(1)
+	}
+
+	// go-scaffold:seed-services
+	svc := user.NewService(
+		user.NewRepository(db), nil, nil, cfg,
+		// go-scaffold:seed-user-service-args
+	)
+	ctx := context.Background()
+
+	if email := os.Getenv("SEED_ADMIN_EMAIL"); email != "" {
+		password := os.Getenv("SEED_ADMIN_PASSWORD")
+		if password == "" {
+			logger.Error("SEED_ADMIN_PASSWORD is required when SEED_ADMIN_EMAIL is set")
+			os.Exit(1)
+		}
+		name := os.Getenv("SEED_ADMIN_NAME")
+		if name == "" {
+			name = "Admin"
+		}
+		u, err := svc.EnsureUser(ctx, email, password, name)
+		if err != nil {
+			logger.Error("seed admin user", "error", err)
+			os.Exit(1)
+		}
+		logger.Info("admin user ready", "email", u.Email, "id", u.ID)
+		// go-scaffold:seed-admin-role
+	}
+
+	if *withFixtures {
+		seedFixtures(ctx, svc, logger)
+	}
+}
+
+func seedFixtures(ctx context.Context, svc *user.Service, logger *slog.Logger) {
+	fixtures := []struct{ email, name string }{
+		{email: "dev.one@example.com", name: "Dev One"},
+		{email: "dev.two@example.com", name: "Dev Two"},
+	}
+	for _, f := range fixtures {
+		u, err := svc.EnsureUser(ctx, f.email, "password123", f.name)
+		if err != nil {
+			logger.Error("seed fixture user", "email", f.email, "error", err)
+			continue
+		}
+		logger.Info("fixture user ready", "email", u.Email, "id", u.ID)
+	}
+}

package/templates/add/auth/docs/forgot-password.yaml.hbs

@@ -0,0 +1,19 @@
+post:
+  summary: Request a password reset link
+  description: Always returns the same message whether or not the email exists, to avoid leaking which emails are registered.
+  operationId: forgotPassword
+  tags: [auth]
+  security: []
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema: { $ref: './schemas.yaml#/ForgotPasswordInput' }
+  responses:
+    "200":
+      description: ok
+      content:
+        application/json:
+          schema: { $ref: './schemas.yaml#/MessageResponse' }
+    "400": { $ref: '../common/responses.yaml#/ValidationError' }
+    "429": { $ref: '../common/responses.yaml#/TooManyRequestsError' }

package/templates/add/auth/docs/google-callback.yaml.hbs

@@ -0,0 +1,22 @@
+get:
+  summary: Google OAuth callback
+  description: Redirect target Google sends the browser back to after consent — not called directly by API clients.
+  operationId: googleCallback
+  tags: [auth]
+  security: []
+  parameters:
+    - name: code
+      in: query
+      required: true
+      schema: { type: string }
+    - name: state
+      in: query
+      required: true
+      schema: { type: string }
+  responses:
+    "200":
+      description: ok, refresh_token set as an httpOnly cookie
+      content:
+        application/json:
+          schema: { $ref: './schemas.yaml#/AuthResponse' }
+    "401": { $ref: '../common/responses.yaml#/UnauthorizedError' }

package/templates/add/auth/docs/google-login.yaml.hbs

@@ -0,0 +1,7 @@
+get:
+  summary: Start the Google OAuth login flow
+  operationId: googleLogin
+  tags: [auth]
+  security: []
+  responses:
+    "302": { description: redirect to Google's consent screen }

package/templates/add/auth/docs/login.yaml.hbs

@@ -0,0 +1,19 @@
+post:
+  summary: Log in with email and password
+  operationId: loginUser
+  tags: [auth]
+  security: []
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema: { $ref: './schemas.yaml#/LoginInput' }
+  responses:
+    "200":
+      description: ok, refresh_token set as an httpOnly cookie
+      content:
+        application/json:
+          schema: { $ref: './schemas.yaml#/AuthResponse' }
+    "400": { $ref: '../common/responses.yaml#/ValidationError' }
+    "401": { $ref: '../common/responses.yaml#/UnauthorizedError' }
+    "429": { $ref: '../common/responses.yaml#/TooManyRequestsError' }

package/templates/add/auth/docs/logout.yaml.hbs

@@ -0,0 +1,8 @@
+post:
+  summary: Log out the current session
+  description: Revokes the refresh_token cookie's session and clears the cookie. Always succeeds, even with no cookie.
+  operationId: logoutUser
+  tags: [auth]
+  security: []
+  responses:
+    "204": { description: logged out }

package/templates/add/auth/docs/refresh.yaml.hbs

@@ -0,0 +1,15 @@
+post:
+  summary: Rotate the refresh token cookie for a new access token
+  description: >-
+    Reads refresh_token from the httpOnly cookie (no request body). Reusing an
+    already-rotated-out token revokes the whole session family.
+  operationId: refreshToken
+  tags: [auth]
+  security: []
+  responses:
+    "200":
+      description: ok, a new refresh_token cookie is set
+      content:
+        application/json:
+          schema: { $ref: './schemas.yaml#/AuthResponse' }
+    "401": { $ref: '../common/responses.yaml#/UnauthorizedError' }

package/templates/add/auth/docs/register.yaml.hbs

@@ -0,0 +1,19 @@
+post:
+  summary: Register a new account
+  operationId: registerUser
+  tags: [auth]
+  security: []
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema: { $ref: './schemas.yaml#/RegisterInput' }
+  responses:
+    "201":
+      description: created, refresh_token set as an httpOnly cookie
+      content:
+        application/json:
+          schema: { $ref: './schemas.yaml#/AuthResponse' }
+    "400": { $ref: '../common/responses.yaml#/ValidationError' }
+    "409": { $ref: '../common/responses.yaml#/ConflictError' }
+    "429": { $ref: '../common/responses.yaml#/TooManyRequestsError' }

package/templates/add/auth/docs/reset-password.yaml.hbs

@@ -0,0 +1,16 @@
+post:
+  summary: Reset a password using a reset token
+  description: The token is one-time use (consumed on success) and also revokes every existing refresh token for the account.
+  operationId: resetPassword
+  tags: [auth]
+  security: []
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema: { $ref: './schemas.yaml#/ResetPasswordInput' }
+  responses:
+    "204": { description: password reset }
+    "400": { $ref: '../common/responses.yaml#/ValidationError' }
+    "401": { $ref: '../common/responses.yaml#/UnauthorizedError' }
+    "429": { $ref: '../common/responses.yaml#/TooManyRequestsError' }

package/templates/add/auth/docs/schemas.yaml.hbs

@@ -0,0 +1,58 @@
+RegisterInput:
+  type: object
+  required: [email, password, name]
+  properties:
+    email: { type: string, format: email }
+    password: { type: string, format: password, minLength: 8 }
+    name: { type: string }
+
+LoginInput:
+  type: object
+  required: [email, password]
+  properties:
+    email: { type: string, format: email }
+    password: { type: string, format: password }
+
+ForgotPasswordInput:
+  type: object
+  required: [email]
+  properties:
+    email: { type: string, format: email }
+
+ResetPasswordInput:
+  type: object
+  required: [token, new_password]
+  properties:
+    token: { type: string }
+    new_password: { type: string, format: password, minLength: 8 }
+
+VerifyEmailInput:
+  type: object
+  required: [token]
+  properties:
+    token: { type: string }
+
+# access_token in the body; refresh_token is set as an httpOnly cookie, never
+# echoed back — see toCookieResponse in internal/app/user/dto.go.
+AuthResponse:
+  type: object
+  properties:
+    access_token: { type: string }
+    token_type: { type: string, example: Bearer }
+    expires_in: { type: integer, description: seconds until access_token expires }
+
+MessageResponse:
+  type: object
+  properties:
+    message: { type: string }
+
+MeResponse:
+  type: object
+  properties:
+    id: { type: string, format: uuid }
+    email: { type: string, format: email }
+    name: { type: string }
+    avatar_url: { type: string }
+    email_verified: { type: boolean }
+    # go-scaffold:me-response-fields
+    created_at: { type: string, format: date-time }

package/templates/add/auth/docs/users-me-logout-all.yaml.hbs

@@ -0,0 +1,9 @@
+post:
+  summary: Log out every session for the current user
+  description: Revokes every refresh token for the caller, not just the current one, and clears this request's cookie too.
+  operationId: logoutAllSessions
+  tags: [users]
+  security: [{ bearerAuth: [] }]
+  responses:
+    "204": { description: all sessions logged out }
+    "401": { $ref: '../common/responses.yaml#/UnauthorizedError' }

package/templates/add/auth/docs/users-me-resend-verification.yaml.hbs

@@ -0,0 +1,10 @@
+post:
+  summary: Resend the email verification link
+  operationId: resendVerification
+  tags: [users]
+  security: [{ bearerAuth: [] }]
+  responses:
+    "204": { description: verification email sent }
+    "401": { $ref: '../common/responses.yaml#/UnauthorizedError' }
+    "409": { $ref: '../common/responses.yaml#/ConflictError' }
+    "429": { $ref: '../common/responses.yaml#/TooManyRequestsError' }

package/templates/add/auth/docs/users-me.yaml.hbs

@@ -0,0 +1,12 @@
+get:
+  summary: Get the current user
+  operationId: getMe
+  tags: [users]
+  security: [{ bearerAuth: [] }]
+  responses:
+    "200":
+      description: ok
+      content:
+        application/json:
+          schema: { $ref: './schemas.yaml#/MeResponse' }
+    "401": { $ref: '../common/responses.yaml#/UnauthorizedError' }

package/templates/add/auth/docs/verify-email.yaml.hbs

@@ -0,0 +1,16 @@
+post:
+  summary: Verify an email address using a verification token
+  description: The token is one-time use (GETDEL), reusing an already-consumed token fails.
+  operationId: verifyEmail
+  tags: [auth]
+  security: []
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema: { $ref: './schemas.yaml#/VerifyEmailInput' }
+  responses:
+    "204": { description: email verified }
+    "400": { $ref: '../common/responses.yaml#/ValidationError' }
+    "401": { $ref: '../common/responses.yaml#/UnauthorizedError' }
+    "429": { $ref: '../common/responses.yaml#/TooManyRequestsError' }

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

@@ -0,0 +1,77 @@
+package user
+
+import (
+	"time"
+
+	"{{goModule}}/internal/app/user/model"
+
+	"github.com/google/uuid"
+)
+
+type registerInput struct {
+	Email    string `json:"email" binding:"required,email"`
+	Password string `json:"password" binding:"required,min=8"`
+	Name     string `json:"name" binding:"required"`
+}
+
+type loginInput struct {
+	Email    string `json:"email" binding:"required,email"`
+	Password string `json:"password" binding:"required"`
+}
+
+type forgotPasswordInput struct {
+	Email string `json:"email" binding:"required,email"`
+}
+
+type resetPasswordInput struct {
+	Token       string `json:"token" binding:"required"`
+	NewPassword string `json:"new_password" binding:"required,min=8"`
+}
+
+type verifyEmailInput struct {
+	Token string `json:"token" binding:"required"`
+}
+
+// authResponse is what the service returns internally (both tokens); the
+// handler sends the refresh token as an httpOnly cookie instead of echoing
+// it in the body, so meResponse never carries it — see toCookieResponse.
+type authResponse struct {
+	AccessToken  string `json:"access_token"`
+	RefreshToken string `json:"-"`
+	TokenType    string `json:"token_type"`
+	ExpiresIn    int    `json:"expires_in"`
+}
+
+type authCookieResponse struct {
+	AccessToken string `json:"access_token"`
+	TokenType   string `json:"token_type"`
+	ExpiresIn   int    `json:"expires_in"`
+}
+
+func toCookieResponse(a *authResponse) authCookieResponse {
+	return authCookieResponse{AccessToken: a.AccessToken, TokenType: a.TokenType, ExpiresIn: a.ExpiresIn}
+}
+
+type meResponse struct {
+	ID            uuid.UUID `json:"id"`
+	Email         string    `json:"email"`
+	Name          string    `json:"name"`
+	AvatarURL     string    `json:"avatar_url"`
+	EmailVerified bool      `json:"email_verified"`
+	// go-scaffold:user-me-fields
+	CreatedAt time.Time `json:"created_at"`
+}
+
+func toMeResponse(u *model.User) meResponse {
+	return meResponse{
+		ID:            u.ID,
+		Email:         u.Email,
+		Name:          u.Name,
+		AvatarURL:     u.AvatarURL,
+		EmailVerified: u.EmailVerified,
+		CreatedAt:     u.CreatedAt,
+		// go-scaffold:user-me-values
+	}
+}
+
+// go-scaffold:user-dto

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

@@ -0,0 +1,36 @@
+package user
+
+import (
+	"net/http"
+
+	"{{goModule}}/internal/shared/apperror"
+)
+
+// functions, not vars: the error middleware writes RequestID onto the
+// returned pointer directly — a shared instance would race across
+// concurrent requests.
+
+func errNotFound() *apperror.AppError {
+	return apperror.New(http.StatusNotFound, "USER_NOT_FOUND", "user not found")
+}
+
+func errEmailTaken() *apperror.AppError {
+	return apperror.New(http.StatusConflict, "USER_EMAIL_TAKEN", "email already registered")
+}
+
+// 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.
+func errInvalidCredentials() *apperror.AppError {
+	return apperror.New(http.StatusUnauthorized, "AUTH_INVALID_CREDENTIALS", "invalid email or password")
+}
+
+func errInvalidToken() *apperror.AppError {
+	return apperror.New(http.StatusUnauthorized, "AUTH_INVALID_TOKEN", "invalid or expired refresh token")
+}
+
+func errAlreadyVerified() *apperror.AppError {
+	return apperror.New(http.StatusConflict, "AUTH_ALREADY_VERIFIED", "email is already verified")
+}
+
+// go-scaffold:user-errors

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

@@ -0,0 +1,235 @@
+package user
+
+import (
+	"net/http"
+	"time"
+
+	"{{goModule}}/internal/shared/httpx"
+	"{{goModule}}/internal/shared/middleware"
+	// go-scaffold:user-handler-imports
+
+	"github.com/gin-gonic/gin"
+	"github.com/google/uuid"
+	"github.com/redis/go-redis/v9"
+)
+
+const refreshCookieName = "refresh_token"
+
+// go-scaffold:user-handler-consts
+
+type Handler struct {
+	svc          *Service
+	jwtSecret    string
+	refreshTTL   time.Duration
+	cookieSecure bool
+	rdb          *redis.Client
+	// go-scaffold:user-handler-fields
+}
+
+func NewHandler(
+	svc *Service,
+	jwtSecret string,
+	refreshTTL time.Duration,
+	cookieSecure bool,
+	rdb *redis.Client,
+	// go-scaffold:user-handler-params
+) *Handler {
+	return &Handler{
+		svc:          svc,
+		jwtSecret:    jwtSecret,
+		refreshTTL:   refreshTTL,
+		cookieSecure: cookieSecure,
+		rdb:          rdb,
+		// go-scaffold:user-handler-init
+	}
+}
+
+// Register wires both a public /auth group (register/login/refresh/logout)
+// and a /users group gated by RequireAuth — public vs protected is decided
+// here, per domain, not centrally in main.go.
+func (h *Handler) Register(rg gin.IRouter) {
+	// per-IP, per-route budgets — separate names so a burst on one endpoint
+	// 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)
+
+	authGroup := rg.Group("/auth")
+	authGroup.POST("/register", registerLimit, h.register)
+	authGroup.POST("/login", loginLimit, h.login)
+	authGroup.POST("/refresh", h.refresh)
+	authGroup.POST("/logout", h.logout)
+	authGroup.POST("/forgot-password", forgotPasswordLimit, h.forgotPassword)
+	authGroup.POST("/reset-password", resetPasswordLimit, h.resetPassword)
+	authGroup.POST("/verify-email", verifyEmailLimit, h.verifyEmail)
+	authGroup.GET("/google/login", h.googleLogin)
+	authGroup.GET("/google/callback", h.googleCallback)
+
+	usersGroup := rg.Group("/users", middleware.RequireAuth(h.jwtSecret))
+	usersGroup.GET("/me", h.me)
+	usersGroup.POST("/me/resend-verification", resendVerificationLimit, h.resendVerification)
+	usersGroup.POST("/me/logout-all", h.logoutAll)
+	// go-scaffold:user-routes
+}
+
+func (h *Handler) register(c *gin.Context) {
+	var in registerInput
+	if err := c.ShouldBindJSON(&in); err != nil {
+		c.Error(httpx.BindErr(err))
+		return
+	}
+	auth, err := h.svc.Register(c.Request.Context(), in)
+	if err != nil {
+		c.Error(err)
+		return
+	}
+	h.setRefreshCookie(c, auth.RefreshToken)
+	c.JSON(http.StatusCreated, toCookieResponse(auth))
+}
+
+func (h *Handler) login(c *gin.Context) {
+	var in loginInput
+	if err := c.ShouldBindJSON(&in); err != nil {
+		c.Error(httpx.BindErr(err))
+		return
+	}
+	auth, err := h.svc.Login(c.Request.Context(), in)
+	if err != nil {
+		c.Error(err)
+		return
+	}
+	h.setRefreshCookie(c, auth.RefreshToken)
+	c.JSON(http.StatusOK, toCookieResponse(auth))
+}
+
+func (h *Handler) refresh(c *gin.Context) {
+	raw, err := c.Cookie(refreshCookieName)
+	if err != nil || raw == "" {
+		c.Error(errInvalidToken())
+		return
+	}
+	auth, err := h.svc.Refresh(c.Request.Context(), raw)
+	if err != nil {
+		h.clearRefreshCookie(c)
+		c.Error(err)
+		return
+	}
+	h.setRefreshCookie(c, auth.RefreshToken)
+	c.JSON(http.StatusOK, toCookieResponse(auth))
+}
+
+func (h *Handler) logout(c *gin.Context) {
+	raw, _ := c.Cookie(refreshCookieName)
+	_ = h.svc.Logout(c.Request.Context(), raw)
+	h.clearRefreshCookie(c)
+	c.Status(http.StatusNoContent)
+}
+
+func (h *Handler) forgotPassword(c *gin.Context) {
+	var in forgotPasswordInput
+	if err := c.ShouldBindJSON(&in); err != nil {
+		c.Error(httpx.BindErr(err))
+		return
+	}
+	if err := h.svc.ForgotPassword(c.Request.Context(), in.Email); err != nil {
+		c.Error(err)
+		return
+	}
+	// always the same response, whether or not the email exists — see
+	// Service.ForgotPassword for why.
+	c.JSON(http.StatusOK, gin.H{"message": "if that email exists, a reset link has been sent"})
+}
+
+func (h *Handler) resetPassword(c *gin.Context) {
+	var in resetPasswordInput
+	if err := c.ShouldBindJSON(&in); err != nil {
+		c.Error(httpx.BindErr(err))
+		return
+	}
+	if err := h.svc.ResetPassword(c.Request.Context(), in.Token, in.NewPassword); err != nil {
+		c.Error(err)
+		return
+	}
+	c.Status(http.StatusNoContent)
+}
+
+func (h *Handler) verifyEmail(c *gin.Context) {
+	var in verifyEmailInput
+	if err := c.ShouldBindJSON(&in); err != nil {
+		c.Error(httpx.BindErr(err))
+		return
+	}
+	if err := h.svc.VerifyEmail(c.Request.Context(), in.Token); err != nil {
+		c.Error(err)
+		return
+	}
+	c.Status(http.StatusNoContent)
+}
+
+func (h *Handler) resendVerification(c *gin.Context) {
+	userID := c.MustGet(middleware.UserIDKey).(uuid.UUID)
+	if err := h.svc.ResendVerificationEmail(c.Request.Context(), userID); err != nil {
+		c.Error(err)
+		return
+	}
+	c.Status(http.StatusNoContent)
+}
+
+// logoutAll ends every session for the caller, not just the one making the
+// request — also clears this request's own cookie, since that session is
+// dead too now.
+func (h *Handler) logoutAll(c *gin.Context) {
+	userID := c.MustGet(middleware.UserIDKey).(uuid.UUID)
+	if err := h.svc.LogoutAll(c.Request.Context(), userID); err != nil {
+		c.Error(err)
+		return
+	}
+	h.clearRefreshCookie(c)
+	c.Status(http.StatusNoContent)
+}
+
+func (h *Handler) googleLogin(c *gin.Context) {
+	url, err := h.svc.GoogleLoginURL()
+	if err != nil {
+		c.Error(err)
+		return
+	}
+	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"))
+	if err != nil {
+		c.Error(err)
+		return
+	}
+	h.setRefreshCookie(c, auth.RefreshToken)
+	c.JSON(http.StatusOK, toCookieResponse(auth))
+}
+
+func (h *Handler) me(c *gin.Context) {
+	userID := c.MustGet(middleware.UserIDKey).(uuid.UUID)
+	u, err := h.svc.Get(c.Request.Context(), userID)
+	if err != nil {
+		c.Error(err)
+		return
+	}
+	c.JSON(http.StatusOK, toMeResponse(u))
+}
+
+// go-scaffold:user-handler-funcs
+
+func (h *Handler) setRefreshCookie(c *gin.Context, token string) {
+	c.SetSameSite(http.SameSiteStrictMode)
+	c.SetCookie(refreshCookieName, token, int(h.refreshTTL.Seconds()), "/", "", h.cookieSecure, true)
+}
+
+func (h *Handler) clearRefreshCookie(c *gin.Context) {
+	c.SetSameSite(http.SameSiteStrictMode)
+	c.SetCookie(refreshCookieName, "", -1, "/", "", h.cookieSecure, true)
+}