@nakedev/go-scaffold 0.1.2 → 0.1.3

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

@@ -0,0 +1,159 @@
+package user
+
+import (
+	"context"
+	"time"
+
+	"github.com/google/uuid"
+	"github.com/redis/go-redis/v9"
+)
+
+const (
+	refreshKeyPrefix     = "user:refresh:"      // +hash -> userID, TTL = refreshTTL
+	refreshUserKeyPrefix = "user:refresh:user:"  // +userID -> SET of active token hashes
+	refreshUsedKeyPrefix = "user:refresh:used:"  // +hash -> userID, TTL = refreshTTL (reuse-detection tombstone)
+	pwresetKeyPrefix     = "user:pwreset:"       // +hash -> userID, TTL = resetTTL, GETDEL on consume
+	emailVerifyKeyPrefix = "user:emailverify:"   // +hash -> userID, TTL = emailVerifyTTL, GETDEL on consume
+)
+
+// tokenStore is what Service needs from Redis for refresh tokens — declared
+// consumer-side so it can be faked in tests without a real Redis.
+type tokenStore interface {
+	SetRefreshToken(ctx context.Context, tokenHash string, userID uuid.UUID, ttl time.Duration) error
+	GetRefreshToken(ctx context.Context, tokenHash string) (uuid.UUID, bool, error)
+	DeleteRefreshToken(ctx context.Context, tokenHash string, userID uuid.UUID) error
+	RevokeAllRefreshTokens(ctx context.Context, userID uuid.UUID) error
+	MarkRefreshTokenUsed(ctx context.Context, tokenHash string, userID uuid.UUID, ttl time.Duration) error
+	IsRefreshTokenUsed(ctx context.Context, tokenHash string) (uuid.UUID, bool, error)
+	SetPasswordResetToken(ctx context.Context, tokenHash string, userID uuid.UUID, ttl time.Duration) error
+	ConsumePasswordResetToken(ctx context.Context, tokenHash string) (uuid.UUID, bool, error)
+	SetEmailVerifyToken(ctx context.Context, tokenHash string, userID uuid.UUID, ttl time.Duration) error
+	ConsumeEmailVerifyToken(ctx context.Context, tokenHash string) (uuid.UUID, bool, error)
+}
+
+type redisTokenStore struct {
+	rdb *redis.Client
+}
+
+func NewRedisTokenStore(rdb *redis.Client) *redisTokenStore {
+	return &redisTokenStore{rdb: rdb}
+}
+
+func (s *redisTokenStore) SetRefreshToken(ctx context.Context, tokenHash string, userID uuid.UUID, ttl time.Duration) error {
+	pipe := s.rdb.TxPipeline()
+	pipe.Set(ctx, refreshKeyPrefix+tokenHash, userID.String(), ttl)
+	pipe.SAdd(ctx, refreshUserKeyPrefix+userID.String(), tokenHash)
+	_, err := pipe.Exec(ctx)
+	return err
+}
+
+func (s *redisTokenStore) GetRefreshToken(ctx context.Context, tokenHash string) (uuid.UUID, bool, error) {
+	raw, err := s.rdb.Get(ctx, refreshKeyPrefix+tokenHash).Result()
+	if err == redis.Nil {
+		return uuid.Nil, false, nil
+	}
+	if err != nil {
+		return uuid.Nil, false, err
+	}
+	id, err := uuid.Parse(raw)
+	if err != nil {
+		return uuid.Nil, false, err
+	}
+	return id, true, nil
+}
+
+func (s *redisTokenStore) DeleteRefreshToken(ctx context.Context, tokenHash string, userID uuid.UUID) error {
+	pipe := s.rdb.TxPipeline()
+	pipe.Del(ctx, refreshKeyPrefix+tokenHash)
+	pipe.SRem(ctx, refreshUserKeyPrefix+userID.String(), tokenHash)
+	_, err := pipe.Exec(ctx)
+	return err
+}
+
+// RevokeAllRefreshTokens walks the per-user session set and deletes every
+// active refresh token for that user — used when reuse of an already-rotated
+// token is detected (see Service.Refresh): that means the raw token leaked,
+// so every session, not just the replayed one, is treated as compromised.
+//
+// ponytail: the per-user set has no per-member TTL cleanup of its own — a
+// member outlives its key's TTL as a stale entry until the next revoke or
+// rotation touches it. Self-heals over time; revisit if a single user's
+// session count grows large enough to matter.
+func (s *redisTokenStore) RevokeAllRefreshTokens(ctx context.Context, userID uuid.UUID) error {
+	setKey := refreshUserKeyPrefix + userID.String()
+	hashes, err := s.rdb.SMembers(ctx, setKey).Result()
+	if err != nil {
+		return err
+	}
+	if len(hashes) == 0 {
+		return nil
+	}
+	pipe := s.rdb.TxPipeline()
+	for _, h := range hashes {
+		pipe.Del(ctx, refreshKeyPrefix+h)
+	}
+	pipe.Del(ctx, setKey)
+	_, err = pipe.Exec(ctx)
+	return err
+}
+
+func (s *redisTokenStore) MarkRefreshTokenUsed(ctx context.Context, tokenHash string, userID uuid.UUID, ttl time.Duration) error {
+	return s.rdb.Set(ctx, refreshUsedKeyPrefix+tokenHash, userID.String(), ttl).Err()
+}
+
+func (s *redisTokenStore) IsRefreshTokenUsed(ctx context.Context, tokenHash string) (uuid.UUID, bool, error) {
+	raw, err := s.rdb.Get(ctx, refreshUsedKeyPrefix+tokenHash).Result()
+	if err == redis.Nil {
+		return uuid.Nil, false, nil
+	}
+	if err != nil {
+		return uuid.Nil, false, err
+	}
+	id, err := uuid.Parse(raw)
+	if err != nil {
+		return uuid.Nil, false, err
+	}
+	return id, true, nil
+}
+
+func (s *redisTokenStore) SetPasswordResetToken(ctx context.Context, tokenHash string, userID uuid.UUID, ttl time.Duration) error {
+	return s.rdb.Set(ctx, pwresetKeyPrefix+tokenHash, userID.String(), ttl).Err()
+}
+
+// ConsumePasswordResetToken is one-time-use by construction: GETDEL is
+// atomic, so a token can't be raced into being consumed twice.
+func (s *redisTokenStore) ConsumePasswordResetToken(ctx context.Context, tokenHash string) (uuid.UUID, bool, error) {
+	raw, err := s.rdb.GetDel(ctx, pwresetKeyPrefix+tokenHash).Result()
+	if err == redis.Nil {
+		return uuid.Nil, false, nil
+	}
+	if err != nil {
+		return uuid.Nil, false, err
+	}
+	id, err := uuid.Parse(raw)
+	if err != nil {
+		return uuid.Nil, false, err
+	}
+	return id, true, nil
+}
+
+func (s *redisTokenStore) SetEmailVerifyToken(ctx context.Context, tokenHash string, userID uuid.UUID, ttl time.Duration) error {
+	return s.rdb.Set(ctx, emailVerifyKeyPrefix+tokenHash, userID.String(), ttl).Err()
+}
+
+// ConsumeEmailVerifyToken is one-time-use by construction, same as
+// ConsumePasswordResetToken — GETDEL is atomic.
+func (s *redisTokenStore) ConsumeEmailVerifyToken(ctx context.Context, tokenHash string) (uuid.UUID, bool, error) {
+	raw, err := s.rdb.GetDel(ctx, emailVerifyKeyPrefix+tokenHash).Result()
+	if err == redis.Nil {
+		return uuid.Nil, false, nil
+	}
+	if err != nil {
+		return uuid.Nil, false, err
+	}
+	id, err := uuid.Parse(raw)
+	if err != nil {
+		return uuid.Nil, false, err
+	}
+	return id, true, nil
+}

package/templates/add/auth/internal/shared/middleware/auth.go.hbs

@@ -0,0 +1,64 @@
+package middleware
+
+import (
+	"net/http"
+	"strings"
+
+	"{{goModule}}/internal/shared/apperror"
+
+	"github.com/gin-gonic/gin"
+	"github.com/golang-jwt/jwt/v5"
+	"github.com/google/uuid"
+)
+
+const UserIDKey = "user_id"
+
+// go-scaffold:middleware-auth-keys
+
+// accessClaims mirrors internal/app/user's own claims shape — duplicated
+// rather than imported, since shared/ can never import a domain package.
+// The two are kept in sync by convention: sub = user id, typ = "access",
+// nothing else is load-bearing here.
+type accessClaims struct {
+	Typ string `json:"typ"`
+	// go-scaffold:middleware-auth-claims
+	jwt.RegisteredClaims
+}
+
+// RequireAuth validates a Bearer access token and puts the caller's user id
+// in context. Rejects a refresh token presented as an access token via the
+// typ claim — the two are structurally identical JWTs otherwise.
+func RequireAuth(secret string) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		header := c.GetHeader("Authorization")
+		raw, ok := strings.CutPrefix(header, "Bearer ")
+		if !ok || raw == "" {
+			unauthorized(c)
+			return
+		}
+
+		var claims accessClaims
+		_, err := jwt.ParseWithClaims(raw, &claims, func(*jwt.Token) (any, error) {
+			return []byte(secret), nil
+		}, jwt.WithValidMethods([]string{jwt.SigningMethodHS256.Name}))
+		if err != nil || claims.Typ != "access" {
+			unauthorized(c)
+			return
+		}
+
+		userID, err := uuid.Parse(claims.Subject)
+		if err != nil {
+			unauthorized(c)
+			return
+		}
+
+		c.Set(UserIDKey, userID)
+		// go-scaffold:middleware-auth-context
+		c.Next()
+	}
+}
+
+func unauthorized(c *gin.Context) {
+	c.Error(apperror.New(http.StatusUnauthorized, "UNAUTHORIZED", "missing or invalid access token"))
+	c.Abort()
+}

package/templates/add/auth/internal/shared/middleware/ratelimit.go.hbs

@@ -0,0 +1,44 @@
+package middleware
+
+import (
+	"net/http"
+	"time"
+
+	"{{goModule}}/internal/shared/apperror"
+
+	"github.com/gin-gonic/gin"
+	"github.com/redis/go-redis/v9"
+)
+
+// RateLimit throttles requests per client IP to `limit` within `window`,
+// keyed by `name` (a per-route label so /auth/login and /auth/register don't
+// share a budget) — a fixed-window counter via Redis INCR+EXPIRE.
+//
+// ponytail: fixed-window, not sliding — simple and correct, the tradeoff is
+// a client can burst up to ~2x limit right at a window boundary (limit
+// requests just before it resets, then limit more right after). Good enough
+// for throttling credential-stuffing/spam, not a hard quota; move to a
+// sliding-window log if that boundary burst ever actually matters.
+func RateLimit(rdb *redis.Client, name string, limit int, window time.Duration) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		key := "ratelimit:" + name + ":" + c.ClientIP()
+		ctx := c.Request.Context()
+
+		count, err := rdb.Incr(ctx, key).Result()
+		if err != nil {
+			// fail open: a Redis blip shouldn't take down login/register
+			// entirely — the endpoint's own logic is still the real guard.
+			c.Next()
+			return
+		}
+		if count == 1 {
+			rdb.Expire(ctx, key, window)
+		}
+		if count > int64(limit) {
+			c.Error(apperror.New(http.StatusTooManyRequests, "RATE_LIMITED", "too many requests, try again later"))
+			c.Abort()
+			return
+		}
+		c.Next()
+	}
+}

package/templates/add/auth/migrations/create_identities.down.sql.hbs

@@ -0,0 +1 @@
+DROP TABLE IF EXISTS identities;

package/templates/add/auth/migrations/create_identities.up.sql.hbs

@@ -0,0 +1,11 @@
+CREATE TABLE identities (
+    id            UUID PRIMARY KEY,
+    user_id       UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    provider      VARCHAR(20) NOT NULL,
+    password_hash TEXT,
+    provider_uid  TEXT,
+    created_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
+    UNIQUE (user_id, provider),
+    UNIQUE (provider, provider_uid)
+);

package/templates/add/auth/migrations/create_users.down.sql.hbs

@@ -0,0 +1 @@
+DROP TABLE IF EXISTS users;

package/templates/add/auth/migrations/create_users.up.sql.hbs

@@ -0,0 +1,9 @@
+CREATE TABLE users (
+    id             UUID PRIMARY KEY,
+    email          VARCHAR(255) NOT NULL UNIQUE,
+    name           VARCHAR(255) NOT NULL DEFAULT '',
+    avatar_url     TEXT NOT NULL DEFAULT '',
+    email_verified BOOLEAN NOT NULL DEFAULT false,
+    created_at     TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at     TIMESTAMPTZ NOT NULL DEFAULT now()
+);

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

@@ -0,0 +1,24 @@
+get:
+  summary: List permissions
+  description: The catalog of every permission code roles can be granted — permissions themselves are seeded by migrations, not created via the API.
+  operationId: listPermissions
+  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: './schemas.yaml#/PermissionResponse' }
+    "401": { $ref: '../common/responses.yaml#/UnauthorizedError' }
+    "403": { $ref: '../common/responses.yaml#/ForbiddenError' }

package/templates/add/rbac/docs/role-permissions.yaml.hbs

@@ -0,0 +1,31 @@
+parameters:
+  - name: code
+    in: path
+    required: true
+    schema: { type: string }
+patch:
+  summary: Replace a role's permissions
+  description: >-
+    Rejects unknown permission codes (422), and rejects removing role:manage
+    from the only role that still has it, to avoid locking every admin out
+    of role management (409).
+  operationId: setRolePermissions
+  tags: [rbac]
+  security: [{ bearerAuth: [] }]
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema: { $ref: './schemas.yaml#/SetPermissionsInput' }
+  responses:
+    "200":
+      description: updated
+      content:
+        application/json:
+          schema: { $ref: './schemas.yaml#/RoleResponse' }
+    "400": { $ref: '../common/responses.yaml#/ValidationError' }
+    "401": { $ref: '../common/responses.yaml#/UnauthorizedError' }
+    "403": { $ref: '../common/responses.yaml#/ForbiddenError' }
+    "404": { $ref: '../common/responses.yaml#/NotFoundError' }
+    "409": { $ref: '../common/responses.yaml#/ConflictError' }
+    "422": { $ref: '../common/responses.yaml#/UnprocessableEntityError' }

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

@@ -0,0 +1,17 @@
+parameters:
+  - name: code
+    in: path
+    required: true
+    schema: { type: string }
+delete:
+  summary: Delete a role
+  description: System roles (staff/admin) cannot be deleted, nor can a role still assigned to users.
+  operationId: deleteRole
+  tags: [rbac]
+  security: [{ bearerAuth: [] }]
+  responses:
+    "204": { description: deleted }
+    "401": { $ref: '../common/responses.yaml#/UnauthorizedError' }
+    "403": { $ref: '../common/responses.yaml#/ForbiddenError' }
+    "404": { $ref: '../common/responses.yaml#/NotFoundError' }
+    "409": { $ref: '../common/responses.yaml#/ConflictError' }

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

@@ -0,0 +1,43 @@
+get:
+  summary: List roles
+  operationId: listRoles
+  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: './schemas.yaml#/RoleResponse' }
+    "401": { $ref: '../common/responses.yaml#/UnauthorizedError' }
+    "403": { $ref: '../common/responses.yaml#/ForbiddenError' }
+post:
+  summary: Create a role
+  operationId: createRole
+  tags: [rbac]
+  security: [{ bearerAuth: [] }]
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema: { $ref: './schemas.yaml#/RoleCreateInput' }
+  responses:
+    "201":
+      description: created
+      content:
+        application/json:
+          schema: { $ref: './schemas.yaml#/RoleResponse' }
+    "400": { $ref: '../common/responses.yaml#/ValidationError' }
+    "401": { $ref: '../common/responses.yaml#/UnauthorizedError' }
+    "403": { $ref: '../common/responses.yaml#/ForbiddenError' }
+    "409": { $ref: '../common/responses.yaml#/ConflictError' }

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")
+}