@nakedev/go-scaffold 0.1.2 → 0.1.3

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

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

@@ -0,0 +1,119 @@
+package role
+
+import (
+	"context"
+	"errors"
+	"net/http"
+	"testing"
+
+	"{{goModule}}/internal/app/role/model"
+	"{{goModule}}/internal/shared/apperror"
+)
+
+// fakeRepo = mock of the repository interface, so the service can be tested
+// without a DB — countWithPermission stands in for "how many roles OTHER
+// than the one being edited currently grant PermRoleManage", exactly what
+// CountRolesWithPermission's excludeCode param means.
+type fakeRepo struct {
+	role                *model.Role
+	findErr             error
+	allPermissionCodes  []string
+	countWithPermission int64
+	setPermissionsErr   error
+	deleteErr           error
+}
+
+func (f *fakeRepo) PermissionCodes(context.Context, string) ([]string, error) { return nil, nil }
+func (f *fakeRepo) FindAll(context.Context, int, int) ([]model.Role, error)   { return nil, nil }
+func (f *fakeRepo) FindByCode(context.Context, string) (*model.Role, error) {
+	if f.findErr != nil {
+		return nil, f.findErr
+	}
+	return f.role, nil
+}
+func (f *fakeRepo) Create(context.Context, *model.Role) error { return nil }
+func (f *fakeRepo) SetPermissions(context.Context, string, []string) error {
+	return f.setPermissionsErr
+}
+func (f *fakeRepo) Delete(context.Context, string) error { return f.deleteErr }
+func (f *fakeRepo) FindAllPermissions(context.Context, int, int) ([]model.Permission, error) {
+	return nil, nil
+}
+func (f *fakeRepo) AllPermissionCodes(context.Context) ([]string, error) { return f.allPermissionCodes, nil }
+func (f *fakeRepo) CountRolesWithPermission(context.Context, string, string) (int64, error) {
+	return f.countWithPermission, nil
+}
+
+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_SetPermissions_LastRoleManagerLockout(t *testing.T) {
+	repo := &fakeRepo{
+		role:                &model.Role{Code: "ops", Name: "Ops"},
+		allPermissionCodes:  []string{PermRoleManage, "user:read"},
+		countWithPermission: 0, // no OTHER role grants PermRoleManage
+	}
+	svc := NewService(repo)
+	// dropping PermRoleManage from the only role that has it would lock every admin out
+	_, err := svc.SetPermissions(context.Background(), "ops", []string{"user:read"})
+	if got := status(t, err); got != http.StatusConflict {
+		t.Fatalf("want 409 last-role-manager lockout, got %d", got)
+	}
+}
+
+func TestService_SetPermissions_AllowedWhenAnotherRoleStillManages(t *testing.T) {
+	repo := &fakeRepo{
+		role:                &model.Role{Code: "ops", Name: "Ops"},
+		allPermissionCodes:  []string{PermRoleManage, "user:read"},
+		countWithPermission: 1, // another role still grants PermRoleManage
+	}
+	svc := NewService(repo)
+	if _, err := svc.SetPermissions(context.Background(), "ops", []string{"user:read"}); err != nil {
+		t.Fatalf("expected success when another role still manages roles, got %v", err)
+	}
+}
+
+func TestService_SetPermissions_KeepingRoleManageNeverLocksOut(t *testing.T) {
+	repo := &fakeRepo{
+		role:                &model.Role{Code: "ops", Name: "Ops"},
+		allPermissionCodes:  []string{PermRoleManage},
+		countWithPermission: 0,
+	}
+	svc := NewService(repo)
+	// the guard only fires when PermRoleManage is being dropped — keeping it never trips it
+	if _, err := svc.SetPermissions(context.Background(), "ops", []string{PermRoleManage}); err != nil {
+		t.Fatalf("keeping %s in the new set should never trigger the lockout guard, got %v", PermRoleManage, err)
+	}
+}
+
+func TestService_Delete_LastRoleManagerLockout(t *testing.T) {
+	repo := &fakeRepo{role: &model.Role{Code: "ops"}, countWithPermission: 0}
+	svc := NewService(repo)
+	err := svc.Delete(context.Background(), "ops")
+	if got := status(t, err); got != http.StatusConflict {
+		t.Fatalf("want 409 last-role-manager lockout on delete, got %d", got)
+	}
+}
+
+func TestService_Delete_AllowedWhenAnotherRoleStillManages(t *testing.T) {
+	repo := &fakeRepo{role: &model.Role{Code: "ops"}, countWithPermission: 1}
+	svc := NewService(repo)
+	if err := svc.Delete(context.Background(), "ops"); err != nil {
+		t.Fatalf("expected delete to succeed when another role still manages roles, got %v", err)
+	}
+}
+
+func TestService_Delete_SystemRoleRejected(t *testing.T) {
+	repo := &fakeRepo{role: &model.Role{Code: "admin", IsSystem: true}}
+	svc := NewService(repo)
+	err := svc.Delete(context.Background(), "admin")
+	if got := status(t, err); got != http.StatusConflict {
+		t.Fatalf("want 409 for a system role, got %d", got)
+	}
+}

package/templates/add/rbac/internal/shared/middleware/authz.go.hbs

@@ -0,0 +1,88 @@
+package middleware
+
+import (
+	"context"
+	"net/http"
+	"sync"
+	"time"
+
+	"{{goModule}}/internal/shared/apperror"
+
+	"github.com/gin-gonic/gin"
+)
+
+// Authz answers "does this role have this permission?". shared/ can't import
+// a domain package (see RequireAuth's comment), so the role->permission
+// lookup is injected as a func value from main.go instead of calling the
+// role domain directly.
+type Authz struct {
+	resolve func(ctx context.Context, roleCode string) (map[string]struct{}, error)
+	ttl     time.Duration
+
+	mu    sync.RWMutex
+	cache map[string]cachedPerms
+}
+
+type cachedPerms struct {
+	perms   map[string]struct{}
+	expires time.Time
+}
+
+// NewAuthz builds an Authz that calls resolve on a cache miss. The cache key
+// is the role code, not the user or the request — a handful of roles means
+// a handful of DB round trips per TTL window, independent of traffic.
+func NewAuthz(resolve func(context.Context, string) (map[string]struct{}, error), ttl time.Duration) *Authz {
+	return &Authz{resolve: resolve, ttl: ttl, cache: map[string]cachedPerms{}}
+}
+
+// Require 403s unless the caller's role (set by RequireAuth) grants perm.
+// Must run after RequireAuth.
+func (a *Authz) Require(perm string) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		perms, err := a.permsOf(c.Request.Context(), c.GetString(RoleKey))
+		if err != nil {
+			c.Error(err)
+			c.Abort()
+			return
+		}
+		if _, ok := perms[perm]; !ok {
+			c.Error(apperror.New(http.StatusForbidden, "FORBIDDEN", "insufficient permissions"))
+			c.Abort()
+			return
+		}
+		c.Next()
+	}
+}
+
+// ponytail: process-local cache, a handful of roles x AUTHZ_CACHE_TTL_MIN —
+// a role's permission grants take effect within the TTL, no pub/sub needed.
+// Move to Redis only if instant cross-pod invalidation turns out to matter.
+//
+// Double-checked locking: the common case (cache hit) only needs RLock, so
+// concurrent requests for different roles never block each other. Only a
+// miss takes the exclusive Lock, and only for the one role being resolved —
+// ceiling is that a miss still blocks other roles' misses (not their hits)
+// for the duration of one resolve() call; move to a per-role singleflight
+// if that contention ever actually shows up under load.
+func (a *Authz) permsOf(ctx context.Context, role string) (map[string]struct{}, error) {
+	a.mu.RLock()
+	e, ok := a.cache[role]
+	a.mu.RUnlock()
+	if ok && time.Now().Before(e.expires) {
+		return e.perms, nil
+	}
+
+	a.mu.Lock()
+	defer a.mu.Unlock()
+	// re-check: another goroutine may have refreshed this role while we
+	// were waiting for the write lock.
+	if e, ok := a.cache[role]; ok && time.Now().Before(e.expires) {
+		return e.perms, nil
+	}
+	perms, err := a.resolve(ctx, role)
+	if err != nil {
+		return nil, err
+	}
+	a.cache[role] = cachedPerms{perms: perms, expires: time.Now().Add(a.ttl)}
+	return perms, nil
+}