refactor(api): add granular permission enforcement on admin routes

- add optional `permission` field to route definitions with type validation in `define.js`
- check `hasPermission()` in router after `requireAdmin()` and return 403 if denied
- document `permission` and `skipRateLimit` optional fields in api README
- load user permissions in `AdminPage.server.js` and pass them to client via `user` prop
- use `user.permissions` in `RolesPage` and `UsersPage` to conditionally render actions
- expose permission-gated API routes in `auth/api.js`

src/features/admin/pages/RolesPage.client.js

@@ -8,7 +8,7 @@ import { useToast } from '@zen/core/toast';
 import AdminHeader from '../components/AdminHeader.js';
 import RoleEditModal from '../components/RoleEditModal.client.js';
 
-const RolesPageClient = () => {
+const RolesPageClient = ({ canManage }) => {
     const toast = useToast();
     const [roles, setRoles] = useState([]);
     const [loading, setLoading] = useState(true);
@@ -73,7 +73,7 @@ const RolesPageClient = () => {
             render: (role) => role.is_system ? <Badge variant="default" size="sm">système</Badge> : null,
             skeleton: { height: 'h-4', width: '60px' },
         },
-        {
+        ...(canManage ? [{
             key: 'actions',
             label: '',
             sortable: false,
@@ -99,7 +99,7 @@ const RolesPageClient = () => {
                 </div>
             ),
             skeleton: { height: 'h-8', width: '80px', className: 'rounded-lg' },
-        },
+        }] : []),
     ];
 
     const fetchRoles = async () => {
@@ -161,14 +161,17 @@ const RolesPageClient = () => {
     );
 };
 
-const RolesPage = () => (
-    <div className="flex flex-col gap-4 sm:gap-6 lg:gap-8">
-        <RolesPageHeader />
-        <RolesPageClient />
-    </div>
-);
+const RolesPage = ({ user }) => {
+    const canManage = user?.permissions?.includes('roles.manage');
+    return (
+        <div className="flex flex-col gap-4 sm:gap-6 lg:gap-8">
+            <RolesPageHeader canManage={canManage} />
+            <RolesPageClient canManage={canManage} />
+        </div>
+    );
+};
 
-const RolesPageHeader = () => {
+const RolesPageHeader = ({ canManage }) => {
     const [modalOpen, setModalOpen] = useState(false);
 
     return (
@@ -176,17 +179,19 @@ const RolesPageHeader = () => {
             <AdminHeader
                 title="Rôles"
                 description="Gérez les rôles et leurs permissions"
-                action={
+                action={canManage && (
                     <Button variant="primary" onClick={() => setModalOpen(true)}>
                         Nouveau rôle
                     </Button>
-                }
-            />
-            <RoleEditModal
-                roleId="new"
-                isOpen={modalOpen}
-                onClose={() => setModalOpen(false)}
+                )}
             />
+            {canManage && (
+                <RoleEditModal
+                    roleId="new"
+                    isOpen={modalOpen}
+                    onClose={() => setModalOpen(false)}
+                />
+            )}
         </>
     );
 };