@nakedev/go-scaffold 0.1.2 → 0.1.4

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

@@ -0,0 +1,237 @@
+package user
+
+import (
+	"context"
+	"errors"
+	"net/http"
+	"testing"
+	"time"
+
+	"{{goModule}}/internal/app/user/model"
+	"{{goModule}}/internal/shared/apperror"
+	"{{goModule}}/internal/shared/config"
+
+	"github.com/google/uuid"
+	"gorm.io/gorm"
+)
+
+// fakeTokenStore = in-memory mock of tokenStore, mirroring redisTokenStore's
+// three-map shape (active / used-tombstone / per-user session set) closely
+// enough to exercise rotation + reuse-detection without a real Redis.
+type fakeTokenStore struct {
+	active   map[string]uuid.UUID
+	used     map[string]uuid.UUID
+	sessions map[uuid.UUID]map[string]struct{}
+}
+
+func newFakeTokenStore() *fakeTokenStore {
+	return &fakeTokenStore{
+		active:   map[string]uuid.UUID{},
+		used:     map[string]uuid.UUID{},
+		sessions: map[uuid.UUID]map[string]struct{}{},
+	}
+}
+
+func (f *fakeTokenStore) SetRefreshToken(_ context.Context, hash string, userID uuid.UUID, _ time.Duration) error {
+	f.active[hash] = userID
+	if f.sessions[userID] == nil {
+		f.sessions[userID] = map[string]struct{}{}
+	}
+	f.sessions[userID][hash] = struct{}{}
+	return nil
+}
+func (f *fakeTokenStore) GetRefreshToken(_ context.Context, hash string) (uuid.UUID, bool, error) {
+	id, ok := f.active[hash]
+	return id, ok, nil
+}
+func (f *fakeTokenStore) DeleteRefreshToken(_ context.Context, hash string, userID uuid.UUID) error {
+	delete(f.active, hash)
+	delete(f.sessions[userID], hash)
+	return nil
+}
+func (f *fakeTokenStore) RevokeAllRefreshTokens(_ context.Context, userID uuid.UUID) error {
+	for h := range f.sessions[userID] {
+		delete(f.active, h)
+	}
+	delete(f.sessions, userID)
+	return nil
+}
+func (f *fakeTokenStore) MarkRefreshTokenUsed(_ context.Context, hash string, userID uuid.UUID, _ time.Duration) error {
+	f.used[hash] = userID
+	return nil
+}
+func (f *fakeTokenStore) IsRefreshTokenUsed(_ context.Context, hash string) (uuid.UUID, bool, error) {
+	id, ok := f.used[hash]
+	return id, ok, nil
+}
+func (f *fakeTokenStore) SetPasswordResetToken(context.Context, string, uuid.UUID, time.Duration) error {
+	return nil
+}
+func (f *fakeTokenStore) ConsumePasswordResetToken(context.Context, string) (uuid.UUID, bool, error) {
+	return uuid.Nil, false, nil
+}
+func (f *fakeTokenStore) SetEmailVerifyToken(context.Context, string, uuid.UUID, time.Duration) error {
+	return nil
+}
+func (f *fakeTokenStore) ConsumeEmailVerifyToken(context.Context, string) (uuid.UUID, bool, error) {
+	return uuid.Nil, false, nil
+}
+
+// fakeRepo = mock of the repository interface — only FindByID is exercised
+// by the tests below (Refresh looks the user up after validating the
+// token), the rest just satisfy the interface.
+type fakeRepo struct {
+	user *model.User
+}
+
+func (f *fakeRepo) FindByEmail(context.Context, string) (*model.User, error) {
+	return nil, gorm.ErrRecordNotFound
+}
+func (f *fakeRepo) FindByID(_ context.Context, id uuid.UUID) (*model.User, error) {
+	if f.user != nil && f.user.ID == id {
+		return f.user, nil
+	}
+	return nil, gorm.ErrRecordNotFound
+}
+func (f *fakeRepo) UpdateUser(context.Context, *model.User) error { return nil }
+func (f *fakeRepo) FindAll(context.Context, int, int) ([]model.User, error) { return nil, nil }
+func (f *fakeRepo) FindIdentity(context.Context, uuid.UUID, model.Provider) (*model.Identity, error) {
+	return nil, gorm.ErrRecordNotFound
+}
+func (f *fakeRepo) FindIdentityByProviderUID(context.Context, model.Provider, string) (*model.Identity, error) {
+	return nil, gorm.ErrRecordNotFound
+}
+func (f *fakeRepo) CreateUserWithIdentity(context.Context, *model.User, *model.Identity) error { return nil }
+func (f *fakeRepo) CreateIdentity(context.Context, *model.Identity) error                      { return nil }
+func (f *fakeRepo) UpdateIdentity(context.Context, *model.Identity) error                      { return nil }
+
+type fakeMailer struct{}
+
+func (fakeMailer) Send(string, string, string) error { return nil }
+
+// go-scaffold:user-service-test-types
+
+// newTestService is the one NewService call site every test below shares —
+// keeping it singular means `add rbac`'s marker patch only has one place to
+// add the roleChecker arg it introduces (patching every call site
+// individually would need a marker-per-callsite, easy to miss one).
+func newTestService(repo repository, tokens tokenStore) *Service {
+	return NewService(
+		repo,
+		tokens,
+		fakeMailer{},
+		config.Config{JWTSecret: "test-secret", JWTAccessTTL: time.Minute, JWTRefreshTTL: time.Hour},
+		// go-scaffold:user-service-test-args
+	)
+}
+
+func status(t *testing.T, err error) int {
+	t.Helper()
+	var appErr *apperror.AppError
+	if !errors.As(err, &appErr) {
+		t.Fatalf("expected *apperror.AppError, got %T: %v", err, err)
+	}
+	return appErr.HTTPStatus
+}
+
+func TestService_Refresh_RotatesTheToken(t *testing.T) {
+	ctx := context.Background()
+	userID := uuid.New()
+	tokens := newFakeTokenStore()
+	rawOld := "old-refresh-token"
+	if err := tokens.SetRefreshToken(ctx, hashToken(rawOld), userID, time.Hour); err != nil {
+		t.Fatalf("seed: %v", err)
+	}
+	svc := newTestService(&fakeRepo{user: &model.User{ID: userID, Email: "a@example.com"}}, tokens)
+
+	auth, err := svc.Refresh(ctx, rawOld)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if auth.RefreshToken == "" || auth.RefreshToken == rawOld {
+		t.Fatalf("expected a new, different refresh token, got %q", auth.RefreshToken)
+	}
+	if _, ok, _ := tokens.GetRefreshToken(ctx, hashToken(rawOld)); ok {
+		t.Fatal("expected the old refresh token to be consumed (no longer active) after rotation")
+	}
+	if _, ok, _ := tokens.GetRefreshToken(ctx, hashToken(auth.RefreshToken)); !ok {
+		t.Fatal("expected the newly rotated refresh token to be active")
+	}
+}
+
+func TestService_Refresh_ReplayingARotatedOutTokenRevokesEverySession(t *testing.T) {
+	ctx := context.Background()
+	userID := uuid.New()
+	tokens := newFakeTokenStore()
+	rawOld := "old-refresh-token"
+	rawOtherSession := "another-devices-refresh-token"
+	if err := tokens.SetRefreshToken(ctx, hashToken(rawOld), userID, time.Hour); err != nil {
+		t.Fatalf("seed: %v", err)
+	}
+	if err := tokens.SetRefreshToken(ctx, hashToken(rawOtherSession), userID, time.Hour); err != nil {
+		t.Fatalf("seed: %v", err)
+	}
+	svc := newTestService(&fakeRepo{user: &model.User{ID: userID, Email: "a@example.com"}}, tokens)
+
+	// rotate rawOld once — legitimate use, consumes + tombstones it
+	if _, err := svc.Refresh(ctx, rawOld); err != nil {
+		t.Fatalf("first refresh: unexpected error: %v", err)
+	}
+
+	// replay the now-rotated-out raw value — this is what happens if it leaked
+	_, err := svc.Refresh(ctx, rawOld)
+	if got := status(t, err); got != http.StatusUnauthorized {
+		t.Fatalf("want 401 replaying a rotated-out token, got %d", got)
+	}
+	if _, ok, _ := tokens.GetRefreshToken(ctx, hashToken(rawOtherSession)); ok {
+		t.Fatal("expected reuse of a rotated-out token to revoke every session for that user, but another session's token is still active")
+	}
+}
+
+func TestService_Refresh_UnknownTokenIsRejectedWithoutRevoking(t *testing.T) {
+	ctx := context.Background()
+	userID := uuid.New()
+	tokens := newFakeTokenStore()
+	rawLegit := "a-legit-session-token"
+	if err := tokens.SetRefreshToken(ctx, hashToken(rawLegit), userID, time.Hour); err != nil {
+		t.Fatalf("seed: %v", err)
+	}
+	svc := newTestService(&fakeRepo{user: &model.User{ID: userID}}, tokens)
+
+	_, err := svc.Refresh(ctx, "never-issued-token")
+	if got := status(t, err); got != http.StatusUnauthorized {
+		t.Fatalf("want 401 for an unrecognized token, got %d", got)
+	}
+	if _, ok, _ := tokens.GetRefreshToken(ctx, hashToken(rawLegit)); !ok {
+		t.Fatal("a never-issued token shouldn't revoke unrelated sessions")
+	}
+}
+
+func TestService_LogoutAll_RevokesEverySessionButLeavesOthersAlone(t *testing.T) {
+	ctx := context.Background()
+	userID := uuid.New()
+	otherUserID := uuid.New()
+	tokens := newFakeTokenStore()
+	rawA := "user-session-a"
+	rawB := "user-session-b"
+	rawOther := "other-users-session"
+	for raw, id := range map[string]uuid.UUID{rawA: userID, rawB: userID, rawOther: otherUserID} {
+		if err := tokens.SetRefreshToken(ctx, hashToken(raw), id, time.Hour); err != nil {
+			t.Fatalf("seed: %v", err)
+		}
+	}
+	svc := newTestService(&fakeRepo{user: &model.User{ID: userID}}, tokens)
+
+	if err := svc.LogoutAll(ctx, userID); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if _, ok, _ := tokens.GetRefreshToken(ctx, hashToken(rawA)); ok {
+		t.Fatal("expected session A to be revoked")
+	}
+	if _, ok, _ := tokens.GetRefreshToken(ctx, hashToken(rawB)); ok {
+		t.Fatal("expected session B to be revoked")
+	}
+	if _, ok, _ := tokens.GetRefreshToken(ctx, hashToken(rawOther)); !ok {
+		t.Fatal("expected a different user's session to be untouched by LogoutAll")
+	}
+}

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' }