@nakedev/go-scaffold 0.1.2 → 0.1.4

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

@@ -0,0 +1,37 @@
+RoleCreateInput:
+  type: object
+  required: [code, name]
+  properties:
+    code: { type: string, maxLength: 20, description: "lowercase, digits, underscores only" }
+    name: { type: string }
+
+SetPermissionsInput:
+  type: object
+  properties:
+    permission_codes:
+      type: array
+      items: { type: string }
+      description: "full replacement of the role's permission set — an empty list revokes every permission"
+
+RoleResponse:
+  type: object
+  properties:
+    code: { type: string }
+    name: { type: string }
+    is_system: { type: boolean, description: "staff/admin — seeded, cannot be deleted" }
+    permissions:
+      type: array
+      items: { type: string }
+    created_at: { type: string, format: date-time }
+
+PermissionResponse:
+  type: object
+  properties:
+    code: { type: string }
+    description: { type: string }
+
+SetRoleInput:
+  type: object
+  required: [role]
+  properties:
+    role: { type: string, description: "must be an existing role code" }

package/templates/add/rbac/docs/user-set-role.yaml.hbs

@@ -0,0 +1,23 @@
+parameters:
+  - $ref: '../common/parameters.yaml#/IdParam'
+patch:
+  summary: Change a user's role
+  operationId: setUserRole
+  tags: [rbac]
+  security: [{ bearerAuth: [] }]
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema: { $ref: './schemas.yaml#/SetRoleInput' }
+  responses:
+    "200":
+      description: updated
+      content:
+        application/json:
+          schema: { $ref: '../auth/schemas.yaml#/MeResponse' }
+    "400": { $ref: '../common/responses.yaml#/ValidationError' }
+    "401": { $ref: '../common/responses.yaml#/UnauthorizedError' }
+    "403": { $ref: '../common/responses.yaml#/ForbiddenError' }
+    "404": { $ref: '../common/responses.yaml#/NotFoundError' }
+    "422": { $ref: '../common/responses.yaml#/UnprocessableEntityError' }

package/templates/add/rbac/docs/user.yaml.hbs

@@ -0,0 +1,16 @@
+parameters:
+  - $ref: '../common/parameters.yaml#/IdParam'
+get:
+  summary: Get a user (admin)
+  operationId: adminGetUser
+  tags: [rbac]
+  security: [{ bearerAuth: [] }]
+  responses:
+    "200":
+      description: ok
+      content:
+        application/json:
+          schema: { $ref: '../auth/schemas.yaml#/MeResponse' }
+    "401": { $ref: '../common/responses.yaml#/UnauthorizedError' }
+    "403": { $ref: '../common/responses.yaml#/ForbiddenError' }
+    "404": { $ref: '../common/responses.yaml#/NotFoundError' }

package/templates/add/rbac/docs/users.yaml.hbs

@@ -0,0 +1,23 @@
+get:
+  summary: List users (admin)
+  operationId: adminListUsers
+  tags: [rbac]
+  security: [{ bearerAuth: [] }]
+  parameters:
+    - $ref: '../common/parameters.yaml#/Limit'
+    - $ref: '../common/parameters.yaml#/Offset'
+  responses:
+    "200":
+      description: paginated list
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: '../common/schemas.yaml#/PageEnvelope'
+              - type: object
+                properties:
+                  data:
+                    type: array
+                    items: { $ref: '../auth/schemas.yaml#/MeResponse' }
+    "401": { $ref: '../common/responses.yaml#/UnauthorizedError' }
+    "403": { $ref: '../common/responses.yaml#/ForbiddenError' }

package/templates/add/rbac/internal/app/role/dto.go.hbs

@@ -0,0 +1,40 @@
+package role
+
+import (
+	"time"
+
+	"{{goModule}}/internal/app/role/model"
+)
+
+// response = the DTO sent out (kept separate from the model so a later DB column doesn't leak automatically)
+type response struct {
+	Code        string    `json:"code"`
+	Name        string    `json:"name"`
+	IsSystem    bool      `json:"is_system"`
+	Permissions []string  `json:"permissions"`
+	CreatedAt   time.Time `json:"created_at"`
+}
+
+func toResponse(m *model.Role, perms []string) response {
+	return response{Code: m.Code, Name: m.Name, IsSystem: m.IsSystem, Permissions: perms, CreatedAt: m.CreatedAt}
+}
+
+type CreateInput struct {
+	Code string `json:"code" binding:"required,max=20"`
+	Name string `json:"name" binding:"required"`
+}
+
+// SetPermissionsInput.PermissionCodes is deliberately not `binding:"required"`
+// — an empty list is valid (it revokes every permission the role had).
+type SetPermissionsInput struct {
+	PermissionCodes []string `json:"permission_codes"`
+}
+
+type permissionResponse struct {
+	Code        string `json:"code"`
+	Description string `json:"description"`
+}
+
+func toPermissionResponse(m *model.Permission) permissionResponse {
+	return permissionResponse{Code: m.Code, Description: m.Description}
+}

package/templates/add/rbac/internal/app/role/errors.go.hbs

@@ -0,0 +1,39 @@
+package role
+
+import (
+	"net/http"
+
+	"{{goModule}}/internal/shared/apperror"
+)
+
+// error catalog specific to role — codes carry more meaning than the generic apperror ones
+// 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, "ROLE_NOT_FOUND", "role not found")
+}
+
+func errConflict() *apperror.AppError {
+	return apperror.New(http.StatusConflict, "ROLE_CONFLICT", "role code already exists")
+}
+
+func errHasReferences() *apperror.AppError {
+	return apperror.New(http.StatusConflict, "ROLE_HAS_REFERENCES", "role still has users assigned to it")
+}
+
+func errInvalidCode() *apperror.AppError {
+	return apperror.New(http.StatusUnprocessableEntity, "ROLE_INVALID_CODE", "code must start with a lowercase letter and contain only lowercase letters, digits, or underscores")
+}
+
+func errSystemRole() *apperror.AppError {
+	return apperror.New(http.StatusConflict, "ROLE_IS_SYSTEM", "staff/admin are system roles and cannot be deleted")
+}
+
+func errUnknownPermission() *apperror.AppError {
+	return apperror.New(http.StatusUnprocessableEntity, "ROLE_UNKNOWN_PERMISSION", "one or more permission codes do not exist")
+}
+
+func errLastRoleManager() *apperror.AppError {
+	return apperror.New(http.StatusConflict, "ROLE_LAST_MANAGER", "this is the only role that can manage roles/permissions — grant "+PermRoleManage+" to another role first")
+}

package/templates/add/rbac/internal/app/role/handler.go.hbs

@@ -0,0 +1,101 @@
+package role
+
+import (
+	"net/http"
+
+	"{{goModule}}/internal/shared/httpx"
+	"{{goModule}}/internal/shared/middleware"
+	"{{goModule}}/internal/shared/pagination"
+
+	"github.com/gin-gonic/gin"
+)
+
+// PermRoleManage gates every endpoint in this file — role/permission
+// management is a single admin capability, not split per-action.
+const PermRoleManage = "role:manage"
+
+type Handler struct {
+	svc       *Service
+	jwtSecret string
+	authz     *middleware.Authz
+}
+
+func NewHandler(svc *Service, jwtSecret string, authz *middleware.Authz) *Handler {
+	return &Handler{svc: svc, jwtSecret: jwtSecret, authz: authz}
+}
+
+// Register wires role's routes onto the router group (takes an IRouter so it can be nested under /v1)
+func (h *Handler) Register(rg gin.IRouter) {
+	roles := rg.Group("/roles", middleware.RequireAuth(h.jwtSecret), h.authz.Require(PermRoleManage))
+	roles.GET("", h.list)
+	roles.POST("", h.create)
+	roles.PATCH("/:code/permissions", h.setPermissions)
+	roles.DELETE("/:code", h.delete)
+
+	perms := rg.Group("/permissions", middleware.RequireAuth(h.jwtSecret), h.authz.Require(PermRoleManage))
+	perms.GET("", h.listPermissions)
+}
+
+func (h *Handler) list(c *gin.Context) {
+	p := pagination.Parse(c)
+	items, err := h.svc.List(c.Request.Context(), p.Limit, p.Offset)
+	if err != nil {
+		c.Error(err)
+		return
+	}
+	out := make([]response, len(items))
+	for i := range items {
+		out[i] = toResponse(&items[i].Role, items[i].Permissions)
+	}
+	c.JSON(http.StatusOK, p.Response(out))
+}
+
+func (h *Handler) create(c *gin.Context) {
+	var in CreateInput
+	if err := c.ShouldBindJSON(&in); err != nil {
+		c.Error(httpx.BindErr(err))
+		return
+	}
+	item, err := h.svc.Create(c.Request.Context(), in)
+	if err != nil {
+		c.Error(err)
+		return
+	}
+	c.JSON(http.StatusCreated, toResponse(&item.Role, item.Permissions))
+}
+
+func (h *Handler) setPermissions(c *gin.Context) {
+	var in SetPermissionsInput
+	if err := c.ShouldBindJSON(&in); err != nil {
+		c.Error(httpx.BindErr(err))
+		return
+	}
+	item, err := h.svc.SetPermissions(c.Request.Context(), c.Param("code"), in.PermissionCodes)
+	if err != nil {
+		c.Error(err)
+		return
+	}
+	c.JSON(http.StatusOK, toResponse(&item.Role, item.Permissions))
+}
+
+func (h *Handler) delete(c *gin.Context) {
+	if err := h.svc.Delete(c.Request.Context(), c.Param("code")); err != nil {
+		c.Error(err)
+		return
+	}
+	c.Status(http.StatusNoContent)
+}
+
+func (h *Handler) listPermissions(c *gin.Context) {
+	p := pagination.Parse(c)
+	items, err := h.svc.ListPermissions(c.Request.Context(), p.Limit, p.Offset)
+	if err != nil {
+		c.Error(err)
+		return
+	}
+	out := make([]permissionResponse, len(items))
+	for i := range items {
+		out[i] = toPermissionResponse(&items[i])
+	}
+	c.JSON(http.StatusOK, p.Response(out))
+}

package/templates/add/rbac/internal/app/role/model/permission.go.hbs

@@ -0,0 +1,9 @@
+package model
+
+// Permission = an action middleware.Authz.Require checks for. Rows are
+// seeded by migration, not admin-created — a permission with no matching
+// Require() call in the code would do nothing.
+type Permission struct {
+	Code        string `json:"code" gorm:"type:varchar(50);primaryKey"`
+	Description string `json:"description" gorm:"not null"`
+}

package/templates/add/rbac/internal/app/role/model/role.go.hbs

@@ -0,0 +1,18 @@
+// Package model holds this domain's GORM tables — a folder (not a single
+// file) so a domain with more than one table can add a file per table
+// without cluttering the domain package's top level.
+package model
+
+import "time"
+
+// Role = an assignable permission level, backed by a real table instead of a
+// hardcoded enum — adding one is a row insert, not a migration + redeploy.
+// Code is the primary key (not a generated UUID): users.role already stores
+// this string, so using it as the join key needs zero data migration.
+type Role struct {
+	Code      string    `json:"code" gorm:"type:varchar(20);primaryKey"`
+	Name      string    `json:"name" gorm:"not null"`
+	IsSystem  bool      `json:"is_system" gorm:"not null;default:false"`
+	CreatedAt time.Time `json:"created_at"`
+	UpdatedAt time.Time `json:"updated_at"`
+}

package/templates/add/rbac/internal/app/role/model/role_permission.go.hbs

@@ -0,0 +1,8 @@
+package model
+
+// RolePermission = the grant between Role and Permission — the one thing
+// admins actually edit; Role and Permission rows themselves stay fixed.
+type RolePermission struct {
+	RoleCode       string `json:"role_code" gorm:"primaryKey;type:varchar(20)"`
+	PermissionCode string `json:"permission_code" gorm:"primaryKey;type:varchar(50)"`
+}

package/templates/add/rbac/internal/app/role/repository.go.hbs

@@ -0,0 +1,96 @@
+package role
+
+import (
+	"context"
+
+	"{{goModule}}/internal/app/role/model"
+
+	"gorm.io/gorm"
+)
+
+// Repository = data access for role (the only place that touches the DB for this domain)
+// every method takes ctx, so a cancelled request cancels the query too
+type Repository struct {
+	db *gorm.DB
+}
+
+func NewRepository(db *gorm.DB) *Repository {
+	return &Repository{db: db}
+}
+
+// PermissionCodes returns the permission codes granted to roleCode.
+func (r *Repository) PermissionCodes(ctx context.Context, roleCode string) ([]string, error) {
+	var codes []string
+	err := r.db.WithContext(ctx).
+		Model(&model.RolePermission{}).
+		Where("role_code = ?", roleCode).
+		Pluck("permission_code", &codes).Error
+	return codes, err
+}
+
+func (r *Repository) FindAll(ctx context.Context, limit, offset int) ([]model.Role, error) {
+	var items []model.Role
+	err := r.db.WithContext(ctx).Order("code").Limit(limit).Offset(offset).Find(&items).Error
+	return items, err
+}
+
+func (r *Repository) FindByCode(ctx context.Context, code string) (*model.Role, error) {
+	var m model.Role
+	if err := r.db.WithContext(ctx).First(&m, "code = ?", code).Error; err != nil {
+		return nil, err
+	}
+	return &m, nil
+}
+
+func (r *Repository) Create(ctx context.Context, m *model.Role) error {
+	return r.db.WithContext(ctx).Create(m).Error
+}
+
+// SetPermissions replaces roleCode's entire permission grant set in one
+// transaction — simpler for a checkbox-style admin UI than diffing
+// add/remove, and cheap at this scale (a handful of rows per role).
+func (r *Repository) SetPermissions(ctx context.Context, roleCode string, permissionCodes []string) error {
+	return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		if err := tx.Where("role_code = ?", roleCode).Delete(&model.RolePermission{}).Error; err != nil {
+			return err
+		}
+		if len(permissionCodes) == 0 {
+			return nil
+		}
+		grants := make([]model.RolePermission, len(permissionCodes))
+		for i, code := range permissionCodes {
+			grants[i] = model.RolePermission{RoleCode: roleCode, PermissionCode: code}
+		}
+		return tx.Create(&grants).Error
+	})
+}
+
+func (r *Repository) Delete(ctx context.Context, code string) error {
+	return r.db.WithContext(ctx).Delete(&model.Role{}, "code = ?", code).Error
+}
+
+func (r *Repository) FindAllPermissions(ctx context.Context, limit, offset int) ([]model.Permission, error) {
+	var items []model.Permission
+	err := r.db.WithContext(ctx).Order("code").Limit(limit).Offset(offset).Find(&items).Error
+	return items, err
+}
+
+// AllPermissionCodes returns every permission code that exists, unpaginated
+// — the catalog is a handful of rows, cheap to fetch whole for validating a
+// SetPermissions request.
+func (r *Repository) AllPermissionCodes(ctx context.Context) ([]string, error) {
+	var codes []string
+	err := r.db.WithContext(ctx).Model(&model.Permission{}).Pluck("code", &codes).Error
+	return codes, err
+}
+
+// CountRolesWithPermission counts roles other than excludeCode that grant
+// permissionCode — used to check whether editing or deleting excludeCode
+// would leave no role holding permissionCode at all.
+func (r *Repository) CountRolesWithPermission(ctx context.Context, permissionCode, excludeCode string) (int64, error) {
+	var count int64
+	err := r.db.WithContext(ctx).Model(&model.RolePermission{}).
+		Where("permission_code = ? AND role_code <> ?", permissionCode, excludeCode).
+		Count(&count).Error
+	return count, err
+}

package/templates/add/rbac/internal/app/role/service.go.hbs

@@ -0,0 +1,210 @@
+package role
+
+import (
+	"context"
+	"errors"
+	"regexp"
+	"slices"
+
+	"{{goModule}}/internal/app/role/model"
+	"{{goModule}}/internal/shared/apperror"
+	"{{goModule}}/internal/shared/dberr"
+
+	"gorm.io/gorm"
+)
+
+// repository = what the service needs from the data layer (declared on the
+// consumer side, so it can be faked in tests)
+type repository interface {
+	PermissionCodes(ctx context.Context, roleCode string) ([]string, error)
+	FindAll(ctx context.Context, limit, offset int) ([]model.Role, error)
+	FindByCode(ctx context.Context, code string) (*model.Role, error)
+	Create(ctx context.Context, m *model.Role) error
+	SetPermissions(ctx context.Context, roleCode string, permissionCodes []string) error
+	Delete(ctx context.Context, code string) error
+	FindAllPermissions(ctx context.Context, limit, offset int) ([]model.Permission, error)
+	AllPermissionCodes(ctx context.Context) ([]string, error)
+	CountRolesWithPermission(ctx context.Context, permissionCode, excludeCode string) (int64, error)
+}
+
+// Service = business logic for role (rules live here, it knows nothing about HTTP)
+type Service struct {
+	repo repository
+}
+
+func NewService(repo repository) *Service {
+	return &Service{repo: repo}
+}
+
+// PermissionsOf resolves roleCode's permission set. This is the func value
+// injected into middleware.Authz from main.go — shared/ can't import a
+// domain package, so it calls this through a func, not a direct dependency.
+func (s *Service) PermissionsOf(ctx context.Context, roleCode string) (map[string]struct{}, error) {
+	codes, err := s.repo.PermissionCodes(ctx, roleCode)
+	if err != nil {
+		return nil, err
+	}
+	set := make(map[string]struct{}, len(codes))
+	for _, c := range codes {
+		set[c] = struct{}{}
+	}
+	return set, nil
+}
+
+// CodeExists reports whether code names a real role — used by user.Service's
+// SetRole to validate a role assignment: AutoMigrate-only test schemas never
+// create the users_role_fkey FK, so that alone can't be relied on to reject
+// an unknown code.
+func (s *Service) CodeExists(ctx context.Context, code string) (bool, error) {
+	if _, err := s.repo.FindByCode(ctx, code); err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return false, nil
+		}
+		return false, err
+	}
+	return true, nil
+}
+
+// roleListItem pairs a role with its granted permission codes — every
+// role-shaped response (list, create, set-permissions) carries both.
+type roleListItem struct {
+	model.Role
+	Permissions []string
+}
+
+func (s *Service) List(ctx context.Context, limit, offset int) ([]roleListItem, error) {
+	roles, err := s.repo.FindAll(ctx, limit, offset)
+	if err != nil {
+		return nil, apperror.NewInternal()
+	}
+	out := make([]roleListItem, len(roles))
+	for i, r := range roles {
+		perms, err := s.repo.PermissionCodes(ctx, r.Code)
+		if err != nil {
+			return nil, apperror.NewInternal()
+		}
+		out[i] = roleListItem{Role: r, Permissions: perms}
+	}
+	return out, nil
+}
+
+// roleCodePattern mirrors the seeded system codes' shape (staff, admin) —
+// lowercase, no spaces, safe to use as a URL path segment and a JWT claim.
+var roleCodePattern = regexp.MustCompile(`^[a-z][a-z0-9_]*$`)
+
+func (s *Service) Create(ctx context.Context, in CreateInput) (*roleListItem, error) {
+	if !roleCodePattern.MatchString(in.Code) {
+		return nil, errInvalidCode()
+	}
+	m := &model.Role{Code: in.Code, Name: in.Name}
+	if err := s.repo.Create(ctx, m); err != nil {
+		if dberr.IsDuplicate(err) {
+			return nil, errConflict()
+		}
+		return nil, apperror.NewInternal()
+	}
+	return &roleListItem{Role: *m, Permissions: []string{}}, nil
+}
+
+// SetPermissions replaces code's entire permission grant set with
+// permissionCodes — a full-replace, not add/remove, matches a checkbox-style
+// admin UI ("here's the new full set") better than diffing.
+func (s *Service) SetPermissions(ctx context.Context, code string, permissionCodes []string) (*roleListItem, error) {
+	m, err := s.repo.FindByCode(ctx, code)
+	if err != nil {
+		return nil, wrapFindErr(err)
+	}
+	if err := s.validatePermissionCodes(ctx, permissionCodes); err != nil {
+		return nil, err
+	}
+	if !slices.Contains(permissionCodes, PermRoleManage) {
+		isLast, err := s.isLastRoleManager(ctx, code)
+		if err != nil {
+			return nil, apperror.NewInternal()
+		}
+		if isLast {
+			return nil, errLastRoleManager()
+		}
+	}
+	if err := s.repo.SetPermissions(ctx, code, permissionCodes); err != nil {
+		// the migration's FK is a backstop for this same check — reachable
+		// only under a race with a concurrent permission deletion.
+		if dberr.IsForeignKey(err) {
+			return nil, errUnknownPermission()
+		}
+		return nil, apperror.NewInternal()
+	}
+	return &roleListItem{Role: *m, Permissions: permissionCodes}, nil
+}
+
+// validatePermissionCodes checks every code against the actual permission
+// catalog — the DB's FK alone isn't enough (AutoMigrate, used in dev/tests,
+// never creates it, only the raw migration SQL does).
+func (s *Service) validatePermissionCodes(ctx context.Context, codes []string) error {
+	all, err := s.repo.AllPermissionCodes(ctx)
+	if err != nil {
+		return apperror.NewInternal()
+	}
+	valid := make(map[string]struct{}, len(all))
+	for _, c := range all {
+		valid[c] = struct{}{}
+	}
+	for _, c := range codes {
+		if _, ok := valid[c]; !ok {
+			return errUnknownPermission()
+		}
+	}
+	return nil
+}
+
+func (s *Service) Delete(ctx context.Context, code string) error {
+	m, err := s.repo.FindByCode(ctx, code)
+	if err != nil {
+		return wrapFindErr(err)
+	}
+	if m.IsSystem {
+		return errSystemRole()
+	}
+	isLast, err := s.isLastRoleManager(ctx, code)
+	if err != nil {
+		return apperror.NewInternal()
+	}
+	if isLast {
+		return errLastRoleManager()
+	}
+	if err := s.repo.Delete(ctx, code); err != nil {
+		if dberr.IsForeignKey(err) {
+			return errHasReferences()
+		}
+		return apperror.NewInternal()
+	}
+	return nil
+}
+
+// isLastRoleManager reports whether code is the only role left granting
+// PermRoleManage — blocks a self-lockout no one could fix back through this
+// same API. Best-effort: reachable only under a race with a concurrent edit
+// to the same permission, not worth a serializable transaction for an
+// admin-only, low-traffic action.
+func (s *Service) isLastRoleManager(ctx context.Context, code string) (bool, error) {
+	others, err := s.repo.CountRolesWithPermission(ctx, PermRoleManage, code)
+	if err != nil {
+		return false, err
+	}
+	return others == 0, nil
+}
+
+func (s *Service) ListPermissions(ctx context.Context, limit, offset int) ([]model.Permission, error) {
+	items, err := s.repo.FindAllPermissions(ctx, limit, offset)
+	if err != nil {
+		return nil, apperror.NewInternal()
+	}
+	return items, nil
+}
+
+func wrapFindErr(err error) error {
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return errNotFound()
+	}
+	return apperror.NewInternal()
+}