@quazardous/qdadm 1.19.3

package/src/security/UsersManager.ts

@@ -0,0 +1,163 @@
+/**
+ * UsersManager - System entity manager for users
+ *
+ * Provides standard user entity with:
+ * - username, password, role fields
+ * - role linked to roles entity via reference
+ * - Admin-only access by default (customizable)
+ *
+ * @example
+ * // In a module:
+ * ctx.userEntity({
+ *   storage: new ApiStorage({ endpoint: '/api/users' }),
+ *   extraFields: {
+ *     email: { type: 'email', label: 'Email' }
+ *   }
+ * })
+ */
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+import { EntityManager } from '../entity/EntityManager'
+import type { FieldConfig } from '../types'
+
+/**
+ * User entity structure
+ */
+export interface UserEntity {
+  id: string | number
+  username: string
+  password?: string
+  role?: string
+  [key: string]: unknown
+}
+
+/**
+ * Field definitions for users
+ */
+export type FieldDefinitions = Record<string, FieldConfig>
+
+/**
+ * Storage interface for users
+ */
+export interface UserStorage {
+  list(params?: unknown): Promise<{ items: UserEntity[]; total: number }>
+  get(id: string | number): Promise<UserEntity | null>
+  create(data: Partial<UserEntity>): Promise<UserEntity>
+  update(id: string | number, data: Partial<UserEntity>): Promise<UserEntity>
+  delete(id: string | number): Promise<void>
+}
+
+/**
+ * Options for UsersManager
+ */
+export interface UsersManagerOptions {
+  storage: UserStorage
+  extraFields?: FieldDefinitions
+  adminPermission?: string
+  fieldOverrides?: {
+    username?: Partial<FieldConfig>
+    password?: Partial<FieldConfig>
+    role?: Partial<FieldConfig>
+  }
+  [key: string]: unknown
+}
+
+// Type for EntityManager base class
+interface EntityManagerInstance {
+  _hasSecurityChecker(): boolean
+  authAdapter: {
+    isGranted(permission: string): boolean
+  }
+}
+
+export class UsersManager extends EntityManager {
+  private _adminPermission: string
+
+  constructor(options: UsersManagerOptions) {
+    const {
+      storage,
+      extraFields = {},
+      adminPermission = 'security:users:manage',
+      fieldOverrides = {},
+      ...rest
+    } = options
+
+    if (!storage) {
+      throw new Error('[UsersManager] storage is required')
+    }
+
+    // Default fields for users
+    const defaultFields: FieldDefinitions = {
+      username: {
+        type: 'text',
+        label: 'Username',
+        required: true,
+        default: '',
+        ...fieldOverrides.username,
+      },
+      password: {
+        type: 'password',
+        label: 'Password',
+        required: true,
+        default: '',
+        listable: false, // Don't show in list view
+        ...fieldOverrides.password,
+      },
+      role: {
+        type: 'select',
+        label: 'Role',
+        reference: { entity: 'roles' }, // Links to roles entity
+        default: 'ROLE_USER',
+        ...fieldOverrides.role,
+      },
+    }
+
+    super({
+      name: 'users',
+      labelField: 'username',
+      system: true, // System-provided entity
+      fields: {
+        ...defaultFields,
+        ...extraFields,
+      },
+      storage,
+      ...rest,
+    })
+
+    this._adminPermission = adminPermission
+  }
+
+  /**
+   * Get admin permission (for external registration)
+   */
+  get adminPermission(): string {
+    return this._adminPermission
+  }
+
+  private _isAdmin(): boolean {
+    const self = this as unknown as EntityManagerInstance
+    if (self._hasSecurityChecker()) {
+      return self.authAdapter.isGranted(this._adminPermission)
+    }
+    return false
+  }
+
+  canRead(): boolean {
+    return this._isAdmin()
+  }
+
+  canCreate(): boolean {
+    // little dumb but should work for simple storages
+    return this._isAdmin()
+  }
+
+  canUpdate(): boolean {
+    // little dumb but should work for simple storages
+    return this._isAdmin()
+  }
+
+  canDelete(): boolean {
+    // little dumb but should work for simple storages
+    return this._isAdmin()
+  }
+}

package/src/security/index.ts

@@ -0,0 +1,77 @@
+/**
+ * Security module - Permission and role management
+ *
+ * Provides:
+ * - PermissionMatcher: Wildcard pattern matching (*, **)
+ * - PermissionRegistry: Central registry for module permissions
+ * - RoleProvider: Interface for role → permissions mapping
+ * - StaticRoleProvider: Config-based roles provider (default)
+ * - EntityRoleProvider: Entity-based roles provider (for UI management)
+ * - PersistableRoleProvider: Load/persist from any source (localStorage, API)
+ * - SecurityModule: System module for roles UI (uses RolesManager)
+ * - RolesManager: System entity manager for roles
+ * - UsersManager: System entity manager for users (linked to roles)
+ *
+ * @example
+ * import {
+ *   PermissionMatcher,
+ *   PermissionRegistry,
+ *   StaticRoleProvider,
+ *   EntityRoleProvider,
+ *   PersistableRoleProvider,
+ *   createLocalStorageRolesProvider,
+ *   UsersManager
+ * } from '@quazardous/qdadm/security'
+ */
+
+export { PermissionMatcher } from './PermissionMatcher'
+export {
+  PermissionRegistry,
+  type PermissionDefinition,
+  type PermissionMeta,
+  type RegisterOptions,
+  type RegisterEntityOptions,
+  type GroupedPermissions,
+} from './PermissionRegistry'
+export {
+  RoleProvider,
+  type RoleMeta,
+  type RoleData,
+  type RoleHierarchyMap,
+  type RolePermissionsMap,
+  type RoleLabelsMap,
+  type RoleProviderContext,
+} from './RolesProvider'
+export {
+  StaticRoleProvider,
+  type StaticRolesProviderConfig,
+} from './StaticRolesProvider'
+export {
+  EntityRoleProvider,
+  type EntityRolesProviderOptions,
+} from './EntityRolesProvider'
+export {
+  PersistableRoleProvider,
+  createLocalStorageRolesProvider,
+  type RoleConfig,
+  type MergeStrategy,
+  type LoadCallback,
+  type PersistCallback,
+  type PersistableRolesProviderOptions,
+  type LocalStorageRolesProviderOptions,
+} from './PersistableRolesProvider'
+export { SecurityModule } from './SecurityModule'
+export { RolesManager, type RolesManagerOptions } from './RolesManager'
+export { UsersManager, type UsersManagerOptions, type UserEntity } from './UsersManager'
+export {
+  RoleProviderStorage,
+  type RoleListParams,
+  type RoleListResult,
+  type RoleInput,
+} from './RolesProviderStorage'
+
+/**
+ * Standard entity actions for CRUD operations
+ * Used by PermissionRegistry.registerEntity()
+ */
+export const ENTITY_ACTIONS = ['read', 'list', 'create', 'update', 'delete'] as const

package/src/security/pages/RoleForm.vue

@@ -0,0 +1,276 @@
+<script setup lang="ts">
+/**
+ * RoleForm - Role create/edit form (standard FormPage pattern)
+ */
+
+import { ref, computed, inject } from 'vue'
+import { useEntityItemFormPage, FormPage, useOrchestrator, PermissionEditor } from '../../index.js'
+import InputText from 'primevue/inputtext'
+import AutoComplete from 'primevue/autocomplete'
+import Chip from 'primevue/chip'
+import type { PermissionRegistry } from '../PermissionRegistry'
+
+/**
+ * Role option for autocomplete
+ */
+interface RoleOption {
+  name: string
+  label: string
+  display: string
+}
+
+/**
+ * Role data from roles provider
+ */
+interface RoleData {
+  label?: string
+  [key: string]: unknown
+}
+
+/**
+ * RolesProvider interface
+ */
+interface RolesProviderInterface {
+  getRoles: () => string[]
+  getRole?: (name: string) => RoleData | null
+}
+
+/**
+ * Roles manager interface
+ */
+interface RolesManager {
+  rolesProvider?: RolesProviderInterface
+}
+
+/**
+ * Autocomplete search event
+ */
+interface AutocompleteSearchEvent {
+  query?: string
+}
+
+/**
+ * Autocomplete select event
+ */
+interface AutocompleteSelectEvent {
+  value: RoleOption
+}
+
+/**
+ * Role form data structure
+ */
+interface RoleFormData {
+  name: string
+  label: string
+  inherits: string[]
+  permissions: string[]
+  [key: string]: unknown
+}
+
+// ============ FORM BUILDER ============
+const form = useEntityItemFormPage({ entity: 'roles' })
+
+// ============ HELPERS ============
+const { getManager } = useOrchestrator()
+const manager = getManager('roles') as RolesManager | null
+
+// Get permissionRegistry directly from Kernel (via provide/inject)
+const permissionRegistry = inject<PermissionRegistry | null>('qdadmPermissionRegistry', null)
+
+// Role options for inheritance (exclude self)
+const allRoles = computed<RoleOption[]>(() => {
+  const currentName = form.data.value?.name as string | undefined
+  const roles = manager?.rolesProvider?.getRoles() || []
+  return roles
+    .filter((name: string) => name !== currentName)
+    .map((name: string) => {
+      const role = manager?.rolesProvider?.getRole?.(name)
+      return {
+        name,
+        label: role?.label || name,
+        display: `${name} (${role?.label || name})`
+      }
+    })
+})
+
+// Autocomplete for roles
+const roleInput = ref<string>('')
+const roleSuggestions = ref<RoleOption[]>([])
+
+function searchRoles(event: AutocompleteSearchEvent): void {
+  const query = (event.query || '').toLowerCase()
+  const selected = (form.data.value.inherits as string[]) || []
+
+  roleSuggestions.value = allRoles.value
+    .filter((r: RoleOption) => !selected.includes(r.name))
+    .filter((r: RoleOption) =>
+      query === '' ||
+      r.name.toLowerCase().includes(query) ||
+      r.label.toLowerCase().includes(query)
+    )
+}
+
+function onRoleSelect(event: AutocompleteSelectEvent): void {
+  const role = event.value
+  const inherits = (form.data.value.inherits as string[]) || []
+  if (role && !inherits.includes(role.name)) {
+    form.data.value.inherits = [...inherits, role.name]
+  }
+  roleInput.value = ''
+}
+
+function removeRole(roleName: string): void {
+  const inherits = (form.data.value.inherits as string[]) || []
+  form.data.value.inherits = inherits.filter((r: string) => r !== roleName)
+}
+
+function getRoleLabel(roleName: string): string {
+  const role = allRoles.value.find((r: RoleOption) => r.name === roleName)
+  return role?.label || roleName
+}
+</script>
+
+<template>
+  <FormPage v-bind="form.props.value" v-on="form.events">
+    <template #fields>
+      <div class="role-form-fields">
+        <!-- Role Name -->
+        <div class="form-field">
+          <label class="font-medium">Role Name</label>
+          <InputText
+            v-model="(form.data.value as RoleFormData).name"
+            :disabled="form.isEdit.value"
+            placeholder="ROLE_ADMIN"
+            class="w-full"
+          />
+          <small class="field-hint">Convention: ROLE_UPPERCASE_NAME</small>
+        </div>
+
+        <!-- Label -->
+        <div class="form-field">
+          <label class="font-medium">Display Label</label>
+          <InputText
+            v-model="(form.data.value as RoleFormData).label"
+            placeholder="Administrator"
+            class="w-full"
+          />
+        </div>
+
+        <!-- Inherits -->
+        <div class="form-field">
+          <label class="font-medium">Inherits From</label>
+          <div class="inherits-editor">
+            <div v-if="((form.data.value as RoleFormData).inherits || []).length > 0" class="inherits-chips">
+              <Chip
+                v-for="roleName in (form.data.value as RoleFormData).inherits"
+                :key="roleName"
+                removable
+                @remove="removeRole(roleName)"
+                class="inherits-chip"
+              >
+                <span class="chip-name">{{ roleName }}</span>
+                <span class="chip-label">({{ getRoleLabel(roleName) }})</span>
+              </Chip>
+            </div>
+            <AutoComplete
+              v-model="roleInput"
+              :suggestions="roleSuggestions"
+              optionLabel="display"
+              placeholder="Type role name..."
+              :minLength="0"
+              completeOnFocus
+              @complete="searchRoles"
+              @item-select="onRoleSelect"
+              dropdown
+              class="w-full"
+            >
+              <template #option="{ option }">
+                <div class="role-option">
+                  <span class="role-name">{{ option.name }}</span>
+                  <span class="role-label">{{ option.label }}</span>
+                </div>
+              </template>
+            </AutoComplete>
+          </div>
+          <small class="field-hint">
+            This role inherits all permissions from selected roles
+          </small>
+        </div>
+
+        <!-- Permissions -->
+        <div class="form-field">
+          <label class="font-medium">
+            Permissions ({{ ((form.data.value as RoleFormData).permissions || []).length }})
+          </label>
+          <PermissionEditor
+            v-model="(form.data.value as RoleFormData).permissions"
+            :permissionRegistry="permissionRegistry"
+            placeholder="Type namespace:action..."
+          />
+        </div>
+      </div>
+    </template>
+  </FormPage>
+</template>
+
+<style scoped>
+/*
+ * Only keep styles here that REQUIRE scoping (:deep, dynamic binding, component-specific overrides).
+ * Generic/reusable styles belong in src/styles/ partials (see _forms.scss, _cards.scss, etc.).
+ */
+/* Form layout - .form-field and .field-hint are global (main.css) */
+.role-form-fields {
+  display: flex;
+  flex-direction: column;
+  gap: 1.5rem;
+}
+
+/* Inherits editor - uses .editor-box pattern */
+.inherits-editor {
+  border: 1px solid var(--p-surface-200);
+  border-radius: 0.5rem;
+  padding: 0.75rem;
+  background: var(--p-surface-50);
+}
+
+/* Inherits chips - uses .editor-chips pattern */
+.inherits-chips {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.5rem;
+  margin-bottom: 0.75rem;
+  padding-bottom: 0.75rem;
+  border-bottom: 1px solid var(--p-surface-200);
+}
+
+.inherits-chip {
+  font-family: monospace;
+  font-size: 0.875rem;
+}
+
+.chip-name {
+  font-weight: 500;
+}
+
+.chip-label {
+  color: var(--p-surface-500);
+  margin-left: 0.25rem;
+}
+
+.role-option {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  gap: 1rem;
+}
+
+.role-name {
+  font-family: monospace;
+  font-weight: 500;
+}
+
+.role-label {
+  color: var(--p-surface-500);
+  font-size: 0.875rem;
+}
+</style>

package/src/security/pages/RoleList.vue

@@ -0,0 +1,123 @@
+<script setup lang="ts">
+/**
+ * RoleList - Role listing page (standard ListPage pattern)
+ */
+
+import { useListPage, ListPage, useOrchestrator } from '../../index.js'
+import Column from 'primevue/column'
+import Message from 'primevue/message'
+import Chip from 'primevue/chip'
+
+/**
+ * RolesProvider interface
+ */
+interface RolesProviderInterface {
+  canPersist?: boolean
+}
+
+/**
+ * Roles manager interface
+ */
+interface RolesManager {
+  rolesProvider?: RolesProviderInterface
+}
+
+// ============ LIST BUILDER ============
+const list = useListPage({ entity: 'roles' })
+
+// ============ SEARCH ============
+list.setSearch({
+  placeholder: 'Search roles...',
+  fields: ['name', 'label']
+})
+
+// ============ HEADER ACTIONS ============
+list.addCreateAction('New Role')
+
+// ============ ROW ACTIONS ============
+list.addEditAction()
+list.addDeleteAction({ labelField: 'label' })
+
+// ============ HELPERS ============
+const { getManager } = useOrchestrator()
+const manager = getManager('roles') as RolesManager | null
+// Storage capability (not user permission) - for showing read-only warning
+const storageCanPersist: boolean = manager?.rolesProvider?.canPersist ?? false
+</script>
+
+<template>
+  <ListPage v-bind="list.props.value" v-on="list.events">
+    <!-- Read-only Warning -->
+    <template #before-table>
+      <Message v-if="!storageCanPersist" severity="info" :closable="false" class="mb-4">
+        <div class="flex align-items-center gap-2">
+          <i class="pi pi-info-circle text-xl"></i>
+          <span>
+            <strong>Read-only:</strong> Roles are configured statically.
+            Use a PersistableRoleProvider for editing.
+          </span>
+        </div>
+      </Message>
+    </template>
+
+    <template #columns>
+      <Column field="name" header="Role" sortable style="width: 25%">
+        <template #body="{ data }">
+          <div>
+            <span class="p-role-label">{{ data.name }}</span>
+            <div v-if="data.label && data.label !== data.name" class="text-sm text-color-secondary mt-1">
+              {{ data.label }}
+            </div>
+          </div>
+        </template>
+      </Column>
+
+      <Column header="Inherits" style="width: 20%">
+        <template #body="{ data }">
+          <div v-if="data.inherits?.length" class="p-role-labels">
+            <span
+              v-for="parent in data.inherits"
+              :key="parent"
+              class="p-role-label"
+            >{{ parent }}</span>
+          </div>
+          <span v-else class="text-color-secondary">-</span>
+        </template>
+      </Column>
+
+      <Column header="Permissions" style="width: 40%">
+        <template #body="{ data }">
+          <div v-if="data.permissions?.length" class="chips-container">
+            <Chip
+              v-for="perm in data.permissions.slice(0, 5)"
+              :key="perm"
+              :label="perm"
+            />
+            <Chip
+              v-if="data.permissions.length > 5"
+              :label="`+${data.permissions.length - 5}`"
+              class="chip-more"
+            />
+          </div>
+          <span v-else class="text-color-secondary">No permissions</span>
+        </template>
+      </Column>
+    </template>
+  </ListPage>
+</template>
+
+<style scoped>
+/*
+ * Only keep styles here that REQUIRE scoping (:deep, dynamic binding, component-specific overrides).
+ * Generic/reusable styles belong in src/styles/ partials (see _forms.scss, _cards.scss, etc.).
+ */
+.chips-container {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.25rem;
+}
+
+.chip-more {
+  border-style: dashed;
+}
+</style>