feat(rbac): add human-readable descriptions for permissions and enhance role creation UI

This commit is contained in:
DESKTOP-RTLN3BA\$punk 2026-01-26 23:56:45 -08:00
parent 55d8594937
commit fd564d3efd
4 changed files with 689 additions and 301 deletions

View file

@ -59,6 +59,58 @@ router = APIRouter()
# ============ Permissions Endpoints ============
# Human-readable descriptions for each permission
PERMISSION_DESCRIPTIONS = {
# Documents
"documents:create": "Add new documents, files, and content to the search space",
"documents:read": "View and search documents in the search space",
"documents:update": "Edit existing documents and their metadata",
"documents:delete": "Remove documents from the search space",
# Chats
"chats:create": "Start new AI chat conversations",
"chats:read": "View chat history and conversations",
"chats:update": "Edit chat titles and settings",
"chats:delete": "Delete chat conversations",
# Comments
"comments:create": "Add comments and annotations to documents",
"comments:read": "View comments on documents",
"comments:delete": "Remove comments from documents",
# LLM Configs
"llm_configs:create": "Add new AI model configurations",
"llm_configs:read": "View AI model settings and configurations",
"llm_configs:update": "Modify AI model configurations",
"llm_configs:delete": "Remove AI model configurations",
# Podcasts
"podcasts:create": "Generate new AI podcasts from content",
"podcasts:read": "Listen to and view generated podcasts",
"podcasts:update": "Edit podcast settings and metadata",
"podcasts:delete": "Remove generated podcasts",
# Connectors
"connectors:create": "Set up new data source integrations",
"connectors:read": "View configured data sources and their status",
"connectors:update": "Modify data source configurations",
"connectors:delete": "Remove data source integrations",
# Logs
"logs:read": "View activity logs and audit trail",
"logs:delete": "Clear activity logs",
# Members
"members:invite": "Send invitations to new team members",
"members:view": "View the list of team members",
"members:remove": "Remove members from the search space",
"members:manage_roles": "Assign and change member roles",
# Roles
"roles:create": "Create new custom roles",
"roles:read": "View available roles and their permissions",
"roles:update": "Modify role permissions",
"roles:delete": "Remove custom roles",
# Settings
"settings:view": "View search space settings",
"settings:update": "Modify search space settings",
"settings:delete": "Delete the entire search space",
# Full access
"*": "Full access to all features and settings",
}
@router.get("/permissions", response_model=PermissionsListResponse)
async def list_all_permissions(
@ -71,12 +123,14 @@ async def list_all_permissions(
for perm in Permission:
# Extract category from permission value (e.g., "documents:read" -> "documents")
category = perm.value.split(":")[0] if ":" in perm.value else "general"
description = PERMISSION_DESCRIPTIONS.get(perm.value, f"Permission for {perm.value}")
permissions.append(
PermissionInfo(
value=perm.value,
name=perm.name,
category=category,
description=description,
)
)

View file

@ -167,6 +167,7 @@ class PermissionInfo(BaseModel):
value: str
name: str
category: str
description: str
class PermissionsListResponse(BaseModel):

View file

@ -122,6 +122,7 @@ import type {
Role,
UpdateRoleRequest,
} from "@/contracts/types/roles.types";
import type { PermissionInfo } from "@/contracts/types/permissions.types";
import { invitesApiService } from "@/lib/apis/invites-api.service";
import { rolesApiService } from "@/lib/apis/roles-api.service";
import { trackSearchSpaceInviteSent, trackSearchSpaceUsersViewed } from "@/lib/posthog/events";
@ -471,13 +472,6 @@ export default function TeamManagementPage() {
className="w-full md:w-auto"
/>
)}
{activeTab === "roles" && hasPermission("roles:create") && (
<CreateRoleDialog
groupedPermissions={groupedPermissions}
onCreateRole={handleCreateRole}
className="w-full md:w-auto"
/>
)}
</div>
<TabsContent value="members" className="space-y-4">
@ -499,8 +493,10 @@ export default function TeamManagementPage() {
loading={rolesLoading}
onUpdateRole={handleUpdateRole}
onDeleteRole={handleDeleteRole}
onCreateRole={handleCreateRole}
canUpdate={hasPermission("roles:update")}
canDelete={hasPermission("roles:delete")}
canCreate={hasPermission("roles:create")}
/>
</TabsContent>
@ -893,21 +889,27 @@ function RolePermissionsDisplay({ permissions }: { permissions: string[] }) {
function RolesTab({
roles,
groupedPermissions: _groupedPermissions,
groupedPermissions,
loading,
onUpdateRole: _onUpdateRole,
onDeleteRole,
onCreateRole,
canUpdate,
canDelete,
canCreate,
}: {
roles: Role[];
groupedPermissions: Record<string, { value: string; name: string; category: string }[]>;
groupedPermissions: Record<string, PermissionWithDescription[]>;
loading: boolean;
onUpdateRole: (roleId: number, data: { permissions?: string[] }) => Promise<Role>;
onDeleteRole: (roleId: number) => Promise<boolean>;
onCreateRole: (data: CreateRoleRequest["data"]) => Promise<Role>;
canUpdate: boolean;
canDelete: boolean;
canCreate: boolean;
}) {
const [showCreateRole, setShowCreateRole] = useState(false);
if (loading) {
return (
<div className="flex items-center justify-center py-12">
@ -921,8 +923,33 @@ function RolesTab({
initial={{ opacity: 0, y: 10 }}
animate={{ opacity: 1, y: 0 }}
exit={{ opacity: 0, y: -10 }}
className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4"
className="space-y-6"
>
{/* Create Role Button / Section */}
{canCreate && !showCreateRole && (
<motion.div
initial={{ opacity: 0 }}
animate={{ opacity: 1 }}
className="flex justify-end"
>
<Button onClick={() => setShowCreateRole(true)} className="gap-2">
<Plus className="h-4 w-4" />
Create Custom Role
</Button>
</motion.div>
)}
{/* Create Role Form */}
{showCreateRole && (
<CreateRoleSection
groupedPermissions={groupedPermissions}
onCreateRole={onCreateRole}
onCancel={() => setShowCreateRole(false)}
/>
)}
{/* Roles Grid */}
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
{roles.map((role, index) => (
<motion.div
key={role.id}
@ -1007,8 +1034,8 @@ function RolesTab({
<AlertDialogHeader>
<AlertDialogTitle>Delete role?</AlertDialogTitle>
<AlertDialogDescription>
This will permanently delete the "{role.name}" role. Members with
this role will lose their permissions.
This will permanently delete the "{role.name}" role. Members
with this role will lose their permissions.
</AlertDialogDescription>
</AlertDialogHeader>
<AlertDialogFooter>
@ -1038,6 +1065,7 @@ function RolesTab({
</Card>
</motion.div>
))}
</div>
</motion.div>
);
}
@ -1461,13 +1489,14 @@ function CreateInviteDialog({
);
}
// ============ Create Role Dialog ============
// ============ Create Role Section ============
// Preset permission sets for quick role creation
// Editor: can create/read/update content, but cannot manage roles, remove members, or change settings
// Viewer: read-only access with ability to create comments
const PRESET_PERMISSIONS = {
editor: [
const ROLE_PRESETS = {
editor: {
name: "Editor",
description: "Can create, read, and update content, but cannot delete or manage team settings",
permissions: [
"documents:create",
"documents:read",
"documents:update",
@ -1491,7 +1520,11 @@ const PRESET_PERMISSIONS = {
"roles:read",
"settings:view",
],
viewer: [
},
viewer: {
name: "Viewer",
description: "Read-only access with ability to add comments",
permissions: [
"documents:read",
"chats:read",
"comments:create",
@ -1504,23 +1537,135 @@ const PRESET_PERMISSIONS = {
"roles:read",
"settings:view",
],
},
contributor: {
name: "Contributor",
description: "Can add and manage their own content",
permissions: [
"documents:create",
"documents:read",
"documents:update",
"chats:create",
"chats:read",
"comments:create",
"comments:read",
"llm_configs:read",
"podcasts:read",
"connectors:read",
"logs:read",
"members:view",
"roles:read",
"settings:view",
],
},
};
function CreateRoleDialog({
// Category display configuration with icons and descriptions
const CATEGORY_DISPLAY: Record<
string,
{ label: string; icon: LucideIcon; description: string; order: number }
> = {
documents: {
label: "Documents",
icon: FileText,
description: "Manage files, notes, and content",
order: 1,
},
chats: {
label: "AI Chats",
icon: MessageSquare,
description: "Create and manage AI conversations",
order: 2,
},
comments: {
label: "Comments",
icon: MessageCircle,
description: "Add annotations to documents",
order: 3,
},
llm_configs: {
label: "AI Models",
icon: Bot,
description: "Configure AI model settings",
order: 4,
},
podcasts: {
label: "Podcasts",
icon: Mic,
description: "Generate AI podcasts from content",
order: 5,
},
connectors: {
label: "Integrations",
icon: Plug,
description: "Connect external data sources",
order: 6,
},
logs: {
label: "Activity Logs",
icon: Logs,
description: "View and manage audit trail",
order: 7,
},
members: {
label: "Team Members",
icon: Users,
description: "Manage team membership",
order: 8,
},
roles: {
label: "Roles",
icon: Shield,
description: "Configure role permissions",
order: 9,
},
settings: {
label: "Settings",
icon: Settings,
description: "Manage search space settings",
order: 10,
},
};
// Action display labels
const ACTION_DISPLAY: Record<string, { label: string; color: string }> = {
create: { label: "Create", color: "text-emerald-600 bg-emerald-500/10" },
read: { label: "View", color: "text-blue-600 bg-blue-500/10" },
update: { label: "Edit", color: "text-amber-600 bg-amber-500/10" },
delete: { label: "Delete", color: "text-red-600 bg-red-500/10" },
invite: { label: "Invite", color: "text-violet-600 bg-violet-500/10" },
view: { label: "View", color: "text-blue-600 bg-blue-500/10" },
remove: { label: "Remove", color: "text-red-600 bg-red-500/10" },
manage_roles: { label: "Manage Roles", color: "text-violet-600 bg-violet-500/10" },
};
// Use the imported PermissionInfo type which now includes description
type PermissionWithDescription = PermissionInfo;
function CreateRoleSection({
groupedPermissions,
onCreateRole,
className,
onCancel,
}: {
groupedPermissions: Record<string, { value: string; name: string; category: string }[]>;
groupedPermissions: Record<string, PermissionWithDescription[]>;
onCreateRole: (data: CreateRoleRequest["data"]) => Promise<Role>;
className?: string;
onCancel: () => void;
}) {
const [open, setOpen] = useState(false);
const [creating, setCreating] = useState(false);
const [name, setName] = useState("");
const [description, setDescription] = useState("");
const [selectedPermissions, setSelectedPermissions] = useState<string[]>([]);
const [isDefault, setIsDefault] = useState(false);
const [expandedCategories, setExpandedCategories] = useState<string[]>([]);
// Sort categories by order
const sortedCategories = useMemo(() => {
return Object.keys(groupedPermissions).sort((a, b) => {
const orderA = CATEGORY_DISPLAY[a]?.order ?? 99;
const orderB = CATEGORY_DISPLAY[b]?.order ?? 99;
return orderA - orderB;
});
}, [groupedPermissions]);
const handleCreate = async () => {
if (!name.trim()) {
@ -1536,11 +1681,7 @@ function CreateRoleDialog({
permissions: selectedPermissions,
is_default: isDefault,
});
setOpen(false);
setName("");
setDescription("");
setSelectedPermissions([]);
setIsDefault(false);
onCancel();
} catch (error) {
console.error("Failed to create role:", error);
} finally {
@ -1548,13 +1689,14 @@ function CreateRoleDialog({
}
};
const togglePermission = (perm: string) => {
const togglePermission = useCallback((perm: string) => {
setSelectedPermissions((prev) =>
prev.includes(perm) ? prev.filter((p) => p !== perm) : [...prev, perm]
);
};
}, []);
const toggleCategory = (category: string) => {
const toggleCategory = useCallback(
(category: string) => {
const categoryPerms = groupedPermissions[category]?.map((p) => p.value) || [];
const allSelected = categoryPerms.every((p) => selectedPermissions.includes(p));
@ -1563,151 +1705,341 @@ function CreateRoleDialog({
} else {
setSelectedPermissions((prev) => [...new Set([...prev, ...categoryPerms])]);
}
};
},
[groupedPermissions, selectedPermissions]
);
const applyPreset = (preset: "editor" | "viewer") => {
setSelectedPermissions(PRESET_PERMISSIONS[preset]);
toast.success(`Applied ${preset === "editor" ? "Editor" : "Viewer"} preset permissions`);
};
const toggleCategoryExpanded = useCallback((category: string) => {
setExpandedCategories((prev) =>
prev.includes(category) ? prev.filter((c) => c !== category) : [...prev, category]
);
}, []);
const applyPreset = useCallback((presetKey: keyof typeof ROLE_PRESETS) => {
const preset = ROLE_PRESETS[presetKey];
setSelectedPermissions(preset.permissions);
if (!name.trim()) {
setName(preset.name);
setDescription(preset.description);
}
toast.success(`Applied ${preset.name} preset`);
}, [name]);
const getCategoryStats = useCallback(
(category: string) => {
const perms = groupedPermissions[category] || [];
const selected = perms.filter((p) => selectedPermissions.includes(p.value)).length;
return { selected, total: perms.length, allSelected: selected === perms.length };
},
[groupedPermissions, selectedPermissions]
);
return (
<Dialog open={open} onOpenChange={setOpen}>
<DialogTrigger asChild>
<Button className={cn("gap-2", className)}>
<Plus className="h-4 w-4" />
Create Role
<motion.div
initial={{ opacity: 0, y: -10 }}
animate={{ opacity: 1, y: 0 }}
exit={{ opacity: 0, y: -10 }}
className="mb-6"
>
<Card className="border-primary/20 bg-gradient-to-br from-primary/5 via-background to-background">
<CardHeader className="pb-4">
<div className="flex items-center justify-between">
<div className="flex items-center gap-3">
<div className="h-10 w-10 rounded-xl bg-primary/10 flex items-center justify-center">
<Plus className="h-5 w-5 text-primary" />
</div>
<div>
<CardTitle className="text-lg">Create Custom Role</CardTitle>
<CardDescription className="text-sm">
Define permissions for a new role in this search space
</CardDescription>
</div>
</div>
<Button variant="ghost" size="icon" onClick={onCancel}>
<Trash2 className="h-4 w-4" />
</Button>
</DialogTrigger>
<DialogContent className="w-[92vw] max-w-[92vw] sm:max-w-xl p-4 md:p-6">
<DialogHeader>
<DialogTitle>Create Custom Role</DialogTitle>
<DialogDescription className="text-xs md:text-sm">
Define a new role with specific permissions for this search space.
</DialogDescription>
</DialogHeader>
<div className="space-y-3 py-2 md:py-4">
<div className="flex flex-col md:grid md:grid-cols-2 gap-3 md:gap-4">
</div>
</CardHeader>
<CardContent className="space-y-6">
{/* Quick Start with Presets */}
<div className="space-y-3">
<Label className="text-sm font-medium">Quick Start with a Template</Label>
<div className="grid grid-cols-1 md:grid-cols-3 gap-3">
{Object.entries(ROLE_PRESETS).map(([key, preset]) => (
<button
key={key}
type="button"
onClick={() => applyPreset(key as keyof typeof ROLE_PRESETS)}
className={cn(
"p-4 rounded-lg border-2 text-left transition-all hover:border-primary/50 hover:bg-primary/5",
selectedPermissions.length > 0 &&
preset.permissions.every((p) => selectedPermissions.includes(p))
? "border-primary bg-primary/10"
: "border-border"
)}
>
<div className="flex items-center gap-2 mb-1">
<ShieldCheck
className={cn(
"h-4 w-4",
key === "editor" && "text-blue-600",
key === "viewer" && "text-gray-600",
key === "contributor" && "text-emerald-600"
)}
/>
<span className="font-medium text-sm">{preset.name}</span>
</div>
<p className="text-xs text-muted-foreground">{preset.description}</p>
</button>
))}
</div>
</div>
{/* Role Details */}
<div className="grid grid-cols-1 md:grid-cols-2 gap-4">
<div className="space-y-2">
<Label htmlFor="role-name">Role Name *</Label>
<Input
id="role-name"
placeholder="e.g., Contributor"
placeholder="e.g., Content Manager"
value={name}
onChange={(e) => setName(e.target.value)}
/>
</div>
<div className="space-y-2">
<Label className="flex items-center gap-2">
<Checkbox checked={isDefault} onCheckedChange={(v) => setIsDefault(!!v)} />
<Label htmlFor="role-description">Description</Label>
<Input
id="role-description"
placeholder="Brief description of this role"
value={description}
onChange={(e) => setDescription(e.target.value)}
/>
</div>
</div>
{/* Default Role Checkbox */}
<div className="flex items-center gap-3 p-3 rounded-lg bg-muted/50">
<Checkbox
id="is-default"
checked={isDefault}
onCheckedChange={(checked) => setIsDefault(checked === true)}
/>
<div className="flex-1">
<Label htmlFor="is-default" className="cursor-pointer font-medium">
Set as default role
</Label>
<p className="text-xs text-muted-foreground">
New invites without a role will use this
New members without a specific role will be assigned this role
</p>
</div>
</div>
<div className="space-y-2">
<Label htmlFor="role-description">Description</Label>
<Textarea
id="role-description"
placeholder="Describe what this role can do..."
value={description}
onChange={(e) => setDescription(e.target.value)}
rows={2}
/>
</div>
<div className="space-y-2">
{/* Permissions Section */}
<div className="space-y-3">
<div className="flex items-center justify-between">
<Label>Permissions ({selectedPermissions.length} selected)</Label>
<div className="flex gap-2">
<Label className="text-sm font-medium">
Permissions ({selectedPermissions.length} selected)
</Label>
<Button
type="button"
variant="outline"
variant="ghost"
size="sm"
className="h-7 text-xs gap-1"
onClick={() => applyPreset("editor")}
className="text-xs h-7"
onClick={() =>
setExpandedCategories(
expandedCategories.length === sortedCategories.length ? [] : sortedCategories
)
}
>
<ShieldCheck className="h-3 w-3 text-blue-600" />
Editor Preset
</Button>
<Button
type="button"
variant="outline"
size="sm"
className="h-7 text-xs gap-1"
onClick={() => applyPreset("viewer")}
>
<ShieldCheck className="h-3 w-3 text-gray-600" />
Viewer Preset
{expandedCategories.length === sortedCategories.length
? "Collapse All"
: "Expand All"}
</Button>
</div>
</div>
<p className="text-xs text-muted-foreground">
Use presets to quickly apply Editor (create/read/update) or Viewer (read-only)
permissions
</p>
<ScrollArea className="h-64 rounded-lg border p-4">
<div className="space-y-4">
{Object.entries(groupedPermissions).map(([category, perms]) => {
const categorySelected = perms.filter((p) =>
selectedPermissions.includes(p.value)
).length;
const allSelected = categorySelected === perms.length;
<div className="space-y-2">
{sortedCategories.map((category) => {
const config = CATEGORY_DISPLAY[category] || {
label: category,
icon: FileText,
description: "",
};
const IconComponent = config.icon;
const stats = getCategoryStats(category);
const isExpanded = expandedCategories.includes(category);
const perms = groupedPermissions[category] || [];
return (
<div key={category} className="space-y-2">
<button
type="button"
className="flex items-center gap-2 cursor-pointer hover:bg-muted/50 p-1 rounded w-full text-left"
onClick={() => toggleCategory(category)}
<div
key={category}
className="rounded-lg border bg-card overflow-hidden"
>
{/* Category Header */}
<div
className={cn(
"flex items-center justify-between p-3 cursor-pointer hover:bg-muted/50 transition-colors",
stats.allSelected && "bg-primary/5"
)}
onClick={() => toggleCategoryExpanded(category)}
onKeyDown={(e) => {
if (e.key === "Enter" || e.key === " ") {
e.preventDefault();
toggleCategoryExpanded(category);
}
}}
tabIndex={0}
role="button"
>
<div className="flex items-center gap-3">
<div
className={cn(
"h-8 w-8 rounded-lg flex items-center justify-center",
stats.selected > 0 ? "bg-primary/10" : "bg-muted"
)}
>
<IconComponent
className={cn(
"h-4 w-4",
stats.selected > 0 ? "text-primary" : "text-muted-foreground"
)}
/>
</div>
<div>
<div className="flex items-center gap-2">
<span className="font-medium text-sm">{config.label}</span>
<Badge
variant={stats.selected > 0 ? "default" : "secondary"}
className="text-xs h-5"
>
{stats.selected}/{stats.total}
</Badge>
</div>
<p className="text-xs text-muted-foreground hidden md:block">
{config.description}
</p>
</div>
</div>
<div className="flex items-center gap-2">
<Checkbox
checked={allSelected}
checked={stats.allSelected}
onCheckedChange={() => toggleCategory(category)}
onClick={(e) => e.stopPropagation()}
aria-label={`Select all ${config.label} permissions`}
/>
<span className="text-sm font-medium capitalize">
{category} ({categorySelected}/{perms.length})
</span>
</button>
<div className="grid grid-cols-2 gap-2 ml-6">
{perms.map((perm) => (
<button
type="button"
key={perm.value}
className="flex items-center gap-2 cursor-pointer text-left"
onClick={() => togglePermission(perm.value)}
<motion.div
animate={{ rotate: isExpanded ? 180 : 0 }}
transition={{ duration: 0.2 }}
>
<Checkbox
checked={selectedPermissions.includes(perm.value)}
onCheckedChange={() => togglePermission(perm.value)}
<svg
className="h-4 w-4 text-muted-foreground"
fill="none"
viewBox="0 0 24 24"
stroke="currentColor"
>
<path
strokeLinecap="round"
strokeLinejoin="round"
strokeWidth={2}
d="M19 9l-7 7-7-7"
/>
<span className="text-xs">{perm.value.split(":")[1]}</span>
</button>
))}
</svg>
</motion.div>
</div>
</div>
{/* Permissions List */}
{isExpanded && (
<motion.div
initial={{ height: 0, opacity: 0 }}
animate={{ height: "auto", opacity: 1 }}
exit={{ height: 0, opacity: 0 }}
transition={{ duration: 0.2 }}
className="border-t"
>
<div className="p-3 space-y-1">
{perms.map((perm) => {
const action = perm.value.split(":")[1];
const actionConfig = ACTION_DISPLAY[action] || {
label: action,
color: "text-gray-600 bg-gray-500/10",
};
const isSelected = selectedPermissions.includes(perm.value);
return (
<div
key={perm.value}
className={cn(
"flex items-center justify-between p-2 rounded-md cursor-pointer transition-colors",
isSelected
? "bg-primary/10 hover:bg-primary/15"
: "hover:bg-muted/50"
)}
onClick={() => togglePermission(perm.value)}
onKeyDown={(e) => {
if (e.key === "Enter" || e.key === " ") {
e.preventDefault();
togglePermission(perm.value);
}
}}
tabIndex={0}
role="checkbox"
aria-checked={isSelected}
>
<div className="flex items-center gap-3 flex-1 min-w-0">
<Checkbox
checked={isSelected}
onCheckedChange={() => togglePermission(perm.value)}
onClick={(e) => e.stopPropagation()}
/>
<div className="flex-1 min-w-0">
<div className="flex items-center gap-2">
<span
className={cn(
"text-xs font-medium px-2 py-0.5 rounded",
actionConfig.color
)}
>
{actionConfig.label}
</span>
</div>
<p className="text-xs text-muted-foreground mt-0.5 truncate">
{perm.description}
</p>
</div>
</div>
</div>
);
})}
</div>
</ScrollArea>
</motion.div>
)}
</div>
);
})}
</div>
</div>
<DialogFooter>
<Button variant="outline" onClick={() => setOpen(false)}>
{/* Actions */}
<div className="flex items-center justify-end gap-3 pt-4 border-t">
<Button variant="outline" onClick={onCancel}>
Cancel
</Button>
<Button onClick={handleCreate} disabled={creating || !name.trim()}>
{creating ? (
<>
<Spinner size="sm" className="mr-2" />
Creating
Creating...
</>
) : (
"Create Role"
<>
<Check className="h-4 w-4 mr-2" />
Create Role
</>
)}
</Button>
</DialogFooter>
</DialogContent>
</Dialog>
</div>
</CardContent>
</Card>
</motion.div>
);
}

View file

@ -4,6 +4,7 @@ export const permissionInfo = z.object({
value: z.string(),
name: z.string(),
category: z.string(),
description: z.string(),
});
/**