@nakedev/go-scaffold 0.4.0 → 0.5.0

package/templates/add/auth/docs/provider-exchange.yaml.hbs

@@ -0,0 +1,40 @@
+post:
+  summary: Exchange a provider authorization code for a local session
+  description: The frontend callback route sends the code, the same state, and the PKCE verifier to the API. The API consumes a one-time server-side state transaction bound to the provider, S256 challenge, and OIDC nonce, uses its exact provider-registered redirect URI, validates the provider response, resolves the local identity, sets an HttpOnly refresh cookie, and returns an access token. The request has no redirect_uri, return_to, or frontend destination; credentials are never placed in a URI.
+  operationId: providerExchange
+  tags: [auth]
+  security: []
+  parameters:
+    - name: provider
+      in: path
+      required: true
+      schema: { type: string, example: google }
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          $ref: "./schemas.yaml#/OAuthExchangeInput"
+  responses:
+    "200":
+      description: local session created; refresh token is set only as an HttpOnly cookie
+      headers:
+        Set-Cookie:
+          description: HttpOnly refresh cookie
+          schema: { type: string }
+        Cache-Control:
+          description: token responses are never cacheable
+          schema: { type: string, example: no-store }
+        Pragma:
+          description: legacy cache prevention for token responses
+          schema: { type: string, example: no-cache }
+      content:
+        application/json:
+          schema:
+            oneOf:
+              - { $ref: "./schemas.yaml#/AuthResponse" }
+              - { $ref: "./schemas.yaml#/MFAChallengeResponse" }
+    "400":
+      description: controlled OAuth error (oauth_denied, oauth_state_invalid, or oauth_failed)
+    "503":
+      description: provider is unavailable or not configured

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

@@ -0,0 +1,31 @@
+get:
+  summary: Start an external OAuth login flow
+  description: Redirects the browser to the configured provider. The browser client supplies state and an S256 PKCE challenge; the server creates a one-time transaction bound to that state, provider, challenge, and OIDC nonce, then uses the exact provider-registered redirect URI. It never accepts a client redirect URI.
+  operationId: providerLogin
+  tags: [auth]
+  security: []
+  parameters:
+    - name: provider
+      in: path
+      required: true
+      schema: { type: string, example: google }
+    - name: state
+      in: query
+      required: true
+      schema: { type: string, minLength: 1 }
+    - name: code_challenge
+      in: query
+      required: true
+      schema:
+        type: string
+        minLength: 43
+        maxLength: 128
+        pattern: '^[A-Za-z0-9._~-]+$'
+    - name: code_challenge_method
+      in: query
+      required: true
+      schema: { type: string, enum: [S256] }
+  responses:
+    "302": { description: redirect to the provider's authorization endpoint }
+    "400": { description: missing or invalid state/PKCE parameters; response uses a controlled OAuth error code }
+    "503": { description: provider is unavailable or not configured }

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

@@ -9,6 +9,13 @@ post:
   responses:
     "200":
       description: ok, a new refresh_token cookie is set
+      headers:
+        Cache-Control:
+          description: token responses are never cacheable
+          schema: { type: string, example: no-store }
+        Pragma:
+          description: legacy cache prevention for token responses
+          schema: { type: string, example: no-cache }
       content:
         application/json:
           schema: { $ref: './schemas.yaml#/AuthResponse' }

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

@@ -11,6 +11,13 @@ post:
   responses:
     "201":
       description: created, refresh_token set as an httpOnly cookie
+      headers:
+        Cache-Control:
+          description: token responses are never cacheable
+          schema: { type: string, example: no-store }
+        Pragma:
+          description: legacy cache prevention for token responses
+          schema: { type: string, example: no-cache }
       content:
         application/json:
           schema: { $ref: './schemas.yaml#/AuthResponse' }

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

@@ -1,6 +1,6 @@
 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.
+  description: The token is consumed only after the password update and refresh-session revocation complete. If the session store is temporarily unavailable, the internal error response restores the token so the caller can retry the complete operation.
   operationId: resetPassword
   tags: [auth]
   security: []

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

@@ -32,8 +32,66 @@ VerifyEmailInput:
   properties:
     token: { type: string }
 
+MFAChallengeInput:
+  type: object
+  required: [challenge, code]
+  additionalProperties: false
+  properties:
+    challenge: { type: string, minLength: 1 }
+    code: { type: string, minLength: 6, maxLength: 16 }
+
+MFACodeInput:
+  type: object
+  required: [code]
+  additionalProperties: false
+  properties:
+    code: { type: string, minLength: 6, maxLength: 16 }
+
+MFAChallengeResponse:
+  type: object
+  required: [mfa_required, challenge]
+  properties:
+    mfa_required: { type: boolean, example: true }
+    challenge: { type: string }
+
+MFAStatus:
+  type: object
+  required: [available, enabled]
+  properties:
+    available: { type: boolean }
+    enabled: { type: boolean }
+
+MFASetupResponse:
+  type: object
+  required: [secret, otpauth_uri]
+  properties:
+    secret: { type: string, description: show once and add to an authenticator app }
+    otpauth_uri: { type: string, format: uri }
+
+MFAConfirmResponse:
+  type: object
+  required: [recovery_codes]
+  properties:
+    recovery_codes:
+      type: array
+      items: { type: string }
+
+OAuthExchangeInput:
+  type: object
+  required: [code, state, code_verifier]
+  additionalProperties: false
+  properties:
+    code: { type: string, minLength: 1 }
+    state: { type: string, minLength: 1 }
+    code_verifier:
+      type: string
+      minLength: 43
+      maxLength: 128
+      pattern: '^[A-Za-z0-9._~-]+$'
+
 # access_token in the body; refresh_token is set as an httpOnly cookie, never
-# echoed back — see toCookieResponse in internal/app/user/dto.go.
+# echoed back — see toCookieResponse in internal/app/user/dto.go. All token
+# responses carry Cache-Control: no-store and Pragma: no-cache.
 AuthResponse:
   type: object
   properties:

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

@@ -0,0 +1,19 @@
+post:
+  summary: Confirm MFA enrollment with a current TOTP code
+  operationId: confirmMyMFA
+  tags: [users]
+  security: [{ bearerAuth: [] }]
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema: { $ref: './schemas.yaml#/MFACodeInput' }
+  responses:
+    "200":
+      description: MFA enabled; recovery codes are returned once
+      content:
+        application/json:
+          schema: { $ref: './schemas.yaml#/MFAConfirmResponse' }
+    "400": { $ref: '../common/responses.yaml#/ValidationError' }
+    "401": { $ref: '../common/responses.yaml#/UnauthorizedError' }
+    "409": { $ref: '../common/responses.yaml#/ConflictError' }

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

@@ -0,0 +1,15 @@
+post:
+  summary: Disable MFA for the current user
+  operationId: disableMyMFA
+  tags: [users]
+  security: [{ bearerAuth: [] }]
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema: { $ref: './schemas.yaml#/MFACodeInput' }
+  responses:
+    "204": { description: MFA disabled }
+    "400": { $ref: '../common/responses.yaml#/ValidationError' }
+    "401": { $ref: '../common/responses.yaml#/UnauthorizedError' }
+    "409": { $ref: '../common/responses.yaml#/ConflictError' }

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

@@ -0,0 +1,14 @@
+post:
+  summary: Start MFA enrollment for the current user
+  operationId: setupMyMFA
+  tags: [users]
+  security: [{ bearerAuth: [] }]
+  responses:
+    "200":
+      description: secret and otpauth URI; enrollment remains disabled until confirmed
+      content:
+        application/json:
+          schema: { $ref: './schemas.yaml#/MFASetupResponse' }
+    "401": { $ref: '../common/responses.yaml#/UnauthorizedError' }
+    "409": { $ref: '../common/responses.yaml#/ConflictError' }
+    "503": { description: MFA is disabled by the operator }

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

@@ -0,0 +1,12 @@
+get:
+  summary: Get the current user's MFA status
+  operationId: getMyMFAStatus
+  tags: [users]
+  security: [{ bearerAuth: [] }]
+  responses:
+    "200":
+      description: MFA availability and enrollment status
+      content:
+        application/json:
+          schema: { $ref: './schemas.yaml#/MFAStatus' }
+    "401": { $ref: '../common/responses.yaml#/UnauthorizedError' }

package/templates/add/auth/internal/app/user/adapters/inbound/http/browser_policy.go.hbs

@@ -0,0 +1,98 @@
+package httpadapter
+
+import (
+	"fmt"
+	"net/http"
+	"net/url"
+	"strings"
+
+	"{{goModule}}/internal/shared/apperror"
+
+	"github.com/gin-gonic/gin"
+)
+
+// requireBrowserOrigin is the CSRF guard for the cross-site cookie mode. CORS
+// controls whether a caller can read the response; this exact origin check
+// independently controls whether a state-changing request may use an ambient
+// refresh cookie.
+func (h *Handler) requireBrowserOrigin(c *gin.Context) bool {
+	if !strings.EqualFold(strings.TrimSpace(h.cookieSameSite), "none") {
+		return true
+	}
+
+	origin := strings.TrimSpace(c.GetHeader("Origin"))
+	if origin == "" {
+		if referer := strings.TrimSpace(c.GetHeader("Referer")); referer != "" {
+			if parsed, err := url.Parse(referer); err == nil && (parsed.Scheme == "http" || parsed.Scheme == "https") && parsed.Host != "" && parsed.User == nil {
+				origin = parsed.Scheme + "://" + parsed.Host
+			}
+		}
+	}
+	if !browserOriginAllowed(origin, h.allowedOrigins) {
+		c.Error(apperror.New(http.StatusForbidden, "CSRF_ORIGIN_INVALID", "request origin is not allowed"))
+		c.Abort()
+		return false
+	}
+	return true
+}
+
+func browserOriginAllowed(origin string, allowed []string) bool {
+	origin = strings.TrimSpace(origin)
+	if _, ok := canonicalBrowserOrigin(origin); !ok {
+		return false
+	}
+	for _, candidate := range allowed {
+		candidate = strings.TrimSpace(candidate)
+		if _, candidateOK := canonicalBrowserOrigin(candidate); candidateOK && candidate == origin {
+			return true
+		}
+	}
+	return false
+}
+
+func canonicalBrowserOrigin(value string) (string, bool) {
+	parsed, err := url.Parse(strings.TrimSpace(value))
+	if err != nil || parsed.User != nil || parsed.Opaque != "" || parsed.Host == "" || parsed.Path != "" || parsed.RawQuery != "" || parsed.Fragment != "" {
+		return "", false
+	}
+	if parsed.Scheme != "http" && parsed.Scheme != "https" {
+		return "", false
+	}
+	return parsed.Scheme + "://" + parsed.Host, true
+}
+
+// ValidateBrowserCookiePolicy ties deployment topology to the attributes used
+// by /auth/refresh. Same-site is the safe local default; cross-site must opt
+// into None + Secure, and production always requires Secure.
+func ValidateBrowserCookiePolicy(topology, sameSite string, secure, production bool) error {
+	if production && !secure {
+		return fmt.Errorf("production browser cookies require COOKIE_SECURE=true")
+	}
+	switch strings.ToLower(strings.TrimSpace(topology)) {
+	case "same-origin", "same-site":
+		if strings.EqualFold(strings.TrimSpace(sameSite), "none") && !secure {
+			return fmt.Errorf("COOKIE_SAMESITE=none requires COOKIE_SECURE=true")
+		}
+		return nil
+	case "cross-site":
+		if !strings.EqualFold(strings.TrimSpace(sameSite), "none") || !secure {
+			return fmt.Errorf("cross-site browser topology requires COOKIE_SAMESITE=none and COOKIE_SECURE=true")
+		}
+		return nil
+	default:
+		return fmt.Errorf("unsupported browser topology %q", topology)
+	}
+}
+
+// sameSiteFrom maps COOKIE_SAMESITE to the net/http constant and defaults to
+// the strictest option for anything unrecognised.
+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/adapters/inbound/http/dto.go.hbs

@@ -0,0 +1,159 @@
+package httpadapter
+
+import (
+	"time"
+
+	userapp "{{goModule}}/internal/app/user/application"
+	userdomain "{{goModule}}/internal/app/user/domain"
+
+	"github.com/google/uuid"
+)
+
+// Request DTOs belong to the HTTP adapter. The application receives the
+// transport-neutral inputs from handler mapping code.
+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 loginExchangeInput struct {
+	Code         string `json:"code"`
+	State        string `json:"state"`
+	CodeVerifier string `json:"code_verifier"`
+}
+
+type loginStartInput struct {
+	State               string
+	CodeChallenge       string
+	CodeChallengeMethod string
+}
+
+func toRegisterInput(in registerInput) userapp.RegisterInput {
+	return userapp.RegisterInput{Email: in.Email, Password: in.Password, Name: in.Name}
+}
+
+func toLoginInput(in loginInput) userapp.LoginInput {
+	return userapp.LoginInput{Email: in.Email, Password: in.Password}
+}
+
+func toLoginStartInput(in loginStartInput) userapp.LoginStartInput {
+	return userapp.LoginStartInput{
+		State: in.State, CodeChallenge: in.CodeChallenge, CodeChallengeMethod: in.CodeChallengeMethod,
+	}
+}
+
+func toLoginExchangeInput(in loginExchangeInput) userapp.LoginExchangeInput {
+	return userapp.LoginExchangeInput{Code: in.Code, State: in.State, CodeVerifier: in.CodeVerifier}
+}
+
+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"`
+}
+
+type mfaCodeInput struct {
+	Code string `json:"code" binding:"required"`
+}
+
+type mfaChallengeInput struct {
+	Challenge string `json:"challenge" binding:"required"`
+	Code      string `json:"code" binding:"required"`
+}
+
+type authCookieResponse struct {
+	AccessToken string `json:"access_token"`
+	TokenType   string `json:"token_type"`
+	ExpiresIn   int    `json:"expires_in"`
+}
+
+type mfaChallengeResponse struct {
+	MFARequired bool   `json:"mfa_required"`
+	Challenge   string `json:"challenge"`
+}
+
+type mfaStatusResponse struct {
+	Available bool `json:"available"`
+	Enabled   bool `json:"enabled"`
+}
+
+type mfaSetupResponse struct {
+	Secret     string `json:"secret"`
+	OTPAuthURI string `json:"otpauth_uri"`
+}
+
+type mfaConfirmResponse struct {
+	RecoveryCodes []string `json:"recovery_codes"`
+}
+
+func toCookieResponse(auth *userapp.AuthResponse) authCookieResponse {
+	return authCookieResponse{AccessToken: auth.AccessToken, TokenType: auth.TokenType, ExpiresIn: auth.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"`
+	Role          string    `json:"role"`
+	// go-scaffold:user-me-fields
+	CreatedAt time.Time `json:"created_at"`
+}
+
+func toMeResponse(user *userdomain.User) meResponse {
+	return meResponse{
+		ID:            user.ID,
+		Email:         user.Email,
+		Name:          user.Name,
+		AvatarURL:     user.AvatarURL,
+		EmailVerified: user.EmailVerified,
+		CreatedAt:     user.CreatedAt,
+		Role:          user.Role,
+		// go-scaffold:user-me-values
+	}
+}
+
+// response is the HTTP representation used by generated methods. It is kept
+// separate from application.Response so JSON naming remains an adapter detail.
+//
+//nolint:unused
+type response struct {
+	ID            uuid.UUID `json:"id"`
+	Email         string    `json:"email"`
+	Name          string    `json:"name"`
+	AvatarURL     string    `json:"avatar_url"`
+	EmailVerified bool      `json:"email_verified"`
+	Role          string    `json:"role"`
+	CreatedAt     time.Time `json:"created_at"`
+	UpdatedAt     time.Time `json:"updated_at"`
+}
+
+//nolint:unused
+func toResponse(out userapp.Response) response {
+	return response{
+		ID: out.ID, Email: out.Email, Name: out.Name, AvatarURL: out.AvatarURL,
+		EmailVerified: out.EmailVerified, Role: out.Role, CreatedAt: out.CreatedAt,
+		UpdatedAt: out.UpdatedAt,
+	}
+}
+
+type setRoleInput struct {
+	Role string `json:"role" binding:"required"`
+}
+
+// go-scaffold:dto
+// go-scaffold:user-dto