admin → RBAC group migration: grant-based access replaces role check

surface.admin.access permission + seeded Admins system group replaces
hardcoded role == "admin" middleware checks. Admin bypass removed from
RequirePermission — all permissions flow through group membership.
Bootstrap, seed, OIDC, and admin handlers sync group membership on
role changes. Demotion/deletion safeguards use group member count.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

server/handlers/admin.go

@@ -100,12 +100,16 @@ func (h *AdminHandler) CreateUser(c *gin.Context) {
 		return
 	}
 
+	// Sync Admins group membership with assigned role.
+	auth.SyncAdminsGroupMembership(c.Request.Context(), h.stores, user.ID, role)
+
 	h.auditLog(c, "user.create", "user", user.ID, nil)
 	c.JSON(http.StatusCreated, user)
 }
 
 func (h *AdminHandler) UpdateUserRole(c *gin.Context) {
 	id := c.Param("id")
+	ctx := c.Request.Context()
 	var req struct {
 		Role string `json:"role" binding:"required"`
 	}
@@ -114,27 +118,30 @@ func (h *AdminHandler) UpdateUserRole(c *gin.Context) {
 		return
 	}
 
-	// Guard: prevent demoting the last admin
-	if req.Role != models.UserRoleAdmin {
-		user, err := h.stores.Users.GetByID(c.Request.Context(), id)
-		if err != nil || user == nil {
-			c.JSON(http.StatusNotFound, gin.H{"error": "user not found"})
+	user, err := h.stores.Users.GetByID(ctx, id)
+	if err != nil || user == nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "user not found"})
+		return
+	}
+
+	// Guard: prevent demoting the last admin.
+	// Count Admins group members — the source of truth for admin access.
+	if req.Role != models.UserRoleAdmin && user.Role == models.UserRoleAdmin {
+		members, _ := h.stores.Groups.ListMembers(ctx, auth.AdminsGroupID)
+		if len(members) <= 1 {
+			c.JSON(http.StatusConflict, gin.H{"error": "cannot demote the last admin"})
 			return
 		}
-		if user.Role == models.UserRoleAdmin {
-			adminCount, _ := h.stores.Users.CountByRole(c.Request.Context(), models.UserRoleAdmin)
-			if adminCount <= 1 {
-				c.JSON(http.StatusConflict, gin.H{"error": "cannot demote the last admin"})
-				return
-			}
-		}
 	}
 
-	if err := h.stores.Users.Update(c.Request.Context(), id, map[string]interface{}{"role": req.Role}); err != nil {
+	if err := h.stores.Users.Update(ctx, id, map[string]interface{}{"role": req.Role}); err != nil {
 		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to update role"})
 		return
 	}
 
+	// Sync Admins group membership with role change.
+	auth.SyncAdminsGroupMembership(ctx, h.stores, id, req.Role)
+
 	h.auditLog(c, "user.role_change", "user", id, gin.H{"role": req.Role})
 	if h.onUserChanged != nil {
 		h.onUserChanged(id)
@@ -254,8 +261,8 @@ func (h *AdminHandler) DeleteUser(c *gin.Context) {
 		return
 	}
 	if user.Role == models.UserRoleAdmin {
-		adminCount, _ := h.stores.Users.CountByRole(c.Request.Context(), models.UserRoleAdmin)
-		if adminCount <= 1 {
+		members, _ := h.stores.Groups.ListMembers(c.Request.Context(), auth.AdminsGroupID)
+		if len(members) <= 1 {
 			c.JSON(http.StatusConflict, gin.H{"error": "cannot delete the last admin"})
 			return
 		}

server/handlers/auth.go

@@ -507,6 +507,7 @@ func BootstrapAdmin(cfg *config.Config, s store.Stores, uekCache ...*crypto.UEKC
 			cache = uekCache[0]
 		}
 		ProbeAndRepairVault(ctx, s, existing.ID, cfg.AdminPassword, cache)
+		ensureAdminsGroupMember(ctx, s, existing.ID)
 		log.Printf("  ✅ Admin user '%s' updated", cfg.AdminUsername)
 		return
 	}
@@ -531,6 +532,7 @@ func BootstrapAdmin(cfg *config.Config, s store.Stores, uekCache ...*crypto.UEKC
 		log.Printf("⚠ Failed to create admin user: %v", err)
 		return
 	}
+	ensureAdminsGroupMember(ctx, s, user.ID)
 	log.Printf("  ✅ Admin user '%s' created", cfg.AdminUsername)
 }
 
@@ -601,6 +603,9 @@ func SeedUsers(cfg *config.Config, s store.Stores, uekCache ...*crypto.UEKCache)
 				cache = uekCache[0]
 			}
 			ProbeAndRepairVault(ctx, s, existing.ID, password, cache)
+			if role == models.UserRoleAdmin {
+				ensureAdminsGroupMember(ctx, s, existing.ID)
+			}
 			log.Printf("  🌱 Seed user '%s' updated (role=%s)", username, role)
 			continue
 		}
@@ -620,10 +625,20 @@ func SeedUsers(cfg *config.Config, s store.Stores, uekCache ...*crypto.UEKCache)
 			log.Printf("⚠ Seed user '%s' failed: %v", username, err)
 			continue
 		}
+		if role == models.UserRoleAdmin {
+			ensureAdminsGroupMember(ctx, s, user.ID)
+		}
 		log.Printf("  🌱 Seed user '%s' created (role=%s, active=true)", username, role)
 	}
 }
 
+// ensureAdminsGroupMember adds userID to the Admins system group (idempotent).
+// Used by BootstrapAdmin and SeedUsers so that admin users receive
+// surface.admin.access through the normal permission resolution path.
+func ensureAdminsGroupMember(ctx context.Context, s store.Stores, userID string) {
+	auth.SyncAdminsGroupMembership(ctx, s, userID, models.UserRoleAdmin)
+}
+
 // IsRegistrationEnabled checks the platform policy.
 func IsRegistrationEnabled(s store.Stores) bool {
 	val, _ := s.Policies.GetBool(context.Background(), "allow_registration")

server/handlers/extension_test.go

@@ -73,7 +73,7 @@ func setupExtensionHarness(t *testing.T) *extensionHarness {
 
 	// Admin extension endpoints
 	admin := api.Group("/admin")
-	admin.Use(middleware.Auth(cfg, stores.Users, userCache), middleware.RequireAdmin())
+	admin.Use(middleware.Auth(cfg, stores.Users, userCache), middleware.RequireAdmin(stores))
 	admin.GET("/extensions", extH.AdminListExtensions)
 	admin.POST("/extensions", extH.AdminInstallExtension)
 	admin.PUT("/extensions/:id", extH.AdminUpdateExtension)
@@ -84,6 +84,7 @@ func setupExtensionHarness(t *testing.T) *extensionHarness {
 		`INSERT INTO users (username, email, password_hash, role, handle, auth_source) VALUES ($1, $2, $3, $4, $5, $6) RETURNING id`,
 		"ext-admin", "ext-admin@test.com", "$2a$10$test", "admin", "ext-admin", "builtin",
 	)
+	database.SeedAdminsGroupMember(t, adminID)
 	adminToken := makeToken(adminID, "ext-admin@test.com", "admin")
 
 	// Seed regular user

server/handlers/notification_test.go

@@ -65,7 +65,7 @@ func setupNotifHarness(t *testing.T) *notifHarness {
 	// Admin broadcast route (v0.28.6)
 	admin := api.Group("/admin")
 	admin.Use(middleware.Auth(cfg, stores.Users, userCache))
-	admin.Use(middleware.RequireAdmin())
+	admin.Use(middleware.RequireAdmin(stores))
 	admin.POST("/notifications/broadcast", notifH.Broadcast)
 
 	// Set up notification service singleton for Broadcast handler
@@ -75,6 +75,7 @@ func setupNotifHarness(t *testing.T) *notifHarness {
 	// Seed admin
 	adminID := database.SeedTestUser(t, "notif-admin", "notif-admin@test.com")
 	database.TestDB.Exec(dialectSQL("UPDATE users SET role = 'admin', is_active = true WHERE id = $1"), adminID)
+	database.SeedAdminsGroupMember(t, adminID)
 	adminToken := makeToken(adminID, "notif-admin@test.com", "admin")
 
 	// Seed regular user