@quazardous/qdadm 2.20.0 → 2.22.0

package/src/kernel/vitePluginCheck.ts

@@ -0,0 +1,61 @@
+/**
+ * Is `qdadmVitePlugin()` in the app's vite config? (#2259)
+ *
+ * qdadm ships raw sources (ADR 0003), and `qdadmVitePlugin()` is what makes the app and qdadm share one copy
+ * of PrimeVue. Without it the app dies at boot on PrimeVue's own `No PrimeVue Toast provided!`, which never
+ * names qdadm. The plugin defines `__QDADM_VITE_PLUGIN__`; the kernel checks it once, in dev, and says what to
+ * add — a log, not a throw, so an app that wires the same config by hand still boots.
+ */
+declare const __QDADM_VITE_PLUGIN__: boolean | undefined
+
+export const MISSING_VITE_PLUGIN_HINT =
+  'qdadmVitePlugin() is missing from vite.config: without it the app and qdadm can load two copies of PrimeVue, ' +
+  "and the app then fails at boot. Add it — import { qdadmVitePlugin } from '@quazardous/qdadm/vite', then " +
+  'plugins: [vue(), qdadmVitePlugin()] — see https://github.com/quazardous/qdadm#quick-start'
+
+/** Whether the app was built with the plugin: the define it sets. */
+export function hasQdadmVitePlugin(): boolean {
+  try {
+    return typeof __QDADM_VITE_PLUGIN__ !== 'undefined' && __QDADM_VITE_PLUGIN__ === true
+  } catch {
+    return false
+  }
+}
+
+const isDev = (): boolean => (import.meta as unknown as { env?: { DEV?: boolean } }).env?.DEV === true
+
+let warned = false
+
+export interface VitePluginCheckOptions {
+  /** Test seams: what the build says, and where the hint goes. */
+  present?: boolean
+  dev?: boolean
+  log?: (message: string) => void
+}
+
+/** Log the hint once, in dev, when the plugin is missing. True when it did. */
+export function warnWithoutQdadmVitePlugin(options: VitePluginCheckOptions = {}): boolean {
+  const present = options.present ?? hasQdadmVitePlugin()
+  const dev = options.dev ?? isDev()
+  if (present || !dev || warned) return false
+  warned = true
+  ;(options.log ?? console.error)(`[qdadm] ${MISSING_VITE_PLUGIN_HINT}`)
+  return true
+}
+
+/** Test seam: forget that the hint was logged. */
+export function resetVitePluginWarning(): void {
+  warned = false
+}
+
+/** PrimeVue's "No PrimeVue Toast provided!", with its usual cause named. Any other error passes through. */
+export function explainMissingToast<T>(use: () => T): T {
+  try {
+    return use()
+  } catch (e) {
+    if (e instanceof Error && /No PrimeVue Toast provided/i.test(e.message)) {
+      throw new Error(`${e.message} The usual cause: ${MISSING_VITE_PLUGIN_HINT}`)
+    }
+    throw e
+  }
+}

package/src/modules/debug/AuthCollector.ts

@@ -41,7 +41,7 @@ export interface AuthEvent {
  * Auth entry types
  */
 export interface AuthEntry extends CollectorEntry {
-  type: 'status' | 'user' | 'impersonated' | 'token' | 'user-permissions' | 'hierarchy' | 'role-permissions' | 'permissions' | 'adapter' | 'error'
+  type: 'status' | 'user' | 'impersonated' | 'token' | 'user-permissions' | 'hierarchy' | 'role-permissions' | 'permissions' | 'delegated-verdicts' | 'adapter' | 'error'
   label?: string
   message?: string
   data?: unknown
@@ -372,6 +372,20 @@ export class AuthCollector extends Collector<AuthEntry> {
           label: 'Permissions',
           data: permissions
         })
+
+        // With a delegated judge (#2225) the role matrix above is not the
+        // authority, and showing it alone would mislead. Show what the
+        // checker actually answers for every registered key — the judge's
+        // verdicts, with the matrix only where the judge abstains.
+        const judged = (this._securityChecker ?? authCtx?.security) as SecurityChecker | null | undefined
+        if (judged?.grant) {
+          entries.push({
+            timestamp: Date.now(),
+            type: 'delegated-verdicts',
+            label: 'Delegated Judgement (security.grant)',
+            data: Object.fromEntries(permissions.map((key: string) => [key, judged.isGranted(key)]))
+          })
+        }
       }
     } catch (e) {
       console.warn('[AuthCollector] Error accessing permissionRegistry:', e)

package/src/modules/debug/DebugModule.ts

@@ -22,6 +22,7 @@ import { AuthCollector } from './AuthCollector'
 import { EntitiesCollector } from './EntitiesCollector'
 import { RouterCollector } from './RouterCollector'
 import { I18nCollector } from './I18nCollector'
+import { RelayCollector, findRelayController } from '@quazardous/qddebug'
 import DebugBar from './components/DebugBar.vue'
 import type { KernelContext } from '../../kernel/KernelContext'
 
@@ -67,6 +68,8 @@ export interface DebugModuleOptions extends ModuleOptions {
   entitiesCollector?: boolean
   routerCollector?: boolean
   i18nCollector?: boolean
+  /** MCP tab (#2231) — only shown where the relay connector is installed */
+  relayCollector?: boolean
   _kernelManaged?: boolean
   /**
    * Existing DebugBridge to register collectors onto. When provided,
@@ -152,6 +155,12 @@ export class DebugModule extends Module {
       this._bridge.addCollector(new I18nCollector(collectorOptions))
     }
 
+    // The MCP tab (#2231), after i18n — and only where the app installed the
+    // relay connector: no connector, nothing to pair, no tab.
+    if (this.options.relayCollector !== false && findRelayController()) {
+      this._bridge.addCollector(new RelayCollector(collectorOptions))
+    }
+
     // Install collectors with context — only when WE own the bridge.
     // External bridges are installed by the host later with a merged
     // context that may include data from other frameworks (e.g. cms).

package/src/modules/debug/components/panels/AuthPanel.vue

@@ -157,6 +157,7 @@ function getIcon(type: string): string {
     permissions: 'pi-list',
     hierarchy: 'pi-sitemap',
     'role-permissions': 'pi-lock',
+    'delegated-verdicts': 'pi-server',
     adapter: 'pi-cog'
   }
   return icons[type] || 'pi-info-circle'

package/src/notifications/NotificationListener.vue

@@ -12,6 +12,7 @@ import { useToast } from 'primevue/usetoast'
 import type { SignalBus } from '../kernel/SignalBus'
 import { useNotifications } from './NotificationStore'
 import type { NotificationSeverity } from './NotificationStore'
+import { explainMissingToast } from '../kernel/vitePluginCheck'
 
 interface ToastEventData {
   summary?: string
@@ -21,7 +22,7 @@ interface ToastEventData {
   forceToast?: boolean
 }
 
-const toast = useToast()
+const toast = explainMissingToast(useToast)
 const signals = inject<SignalBus | null>('qdadmSignals', null)
 const store = useNotifications()
 

package/src/security/RolesProvider.ts

@@ -70,6 +70,14 @@ export interface RoleProviderContext {
   orchestrator?: {
     get: (name: string) => unknown
   }
+  /**
+   * The live permission registry (#2225) — a reference, not a snapshot:
+   * `install` runs before modules register their entities, so read
+   * `getKeys()` later, when you actually fetch.
+   */
+  permissionRegistry?: {
+    getKeys: () => string[]
+  }
   [key: string]: unknown
 }
 

package/src/security/index.ts

@@ -69,6 +69,23 @@ export {
   type RoleListResult,
   type RoleInput,
 } from './RolesProviderStorage'
+export {
+  composeGrants,
+  inheritedGrants,
+  originOf,
+  setGrant,
+  type GrantDefinition,
+  type InheritedGrant,
+  type RoleComposition,
+  type InheritableRole,
+  type GrantOrigin,
+  type GrantCell,
+  type GrantRow,
+  type GrantGroup,
+  type OtherGrant,
+  type GrantsModel,
+  type RoleHierarchySource,
+} from './roleGrants'
 
 /**
  * Standard entity actions for CRUD operations

package/src/security/pages/RoleForm.vue

@@ -1,59 +1,35 @@
 <script setup lang="ts">
 /**
  * RoleForm - Role create/edit form (standard FormPage pattern)
+ *
+ * The composition is edited with RoleGrantsEditor (#2313), fed by the roles provider: here qdadm judges roles in
+ * the front, so it computes what the inherited roles bring itself.
  */
 
-import { ref, computed, inject } from 'vue'
-import { useEntityItemFormPage, FormPage, useOrchestrator, PermissionEditor } from '../../index.js'
+import { computed } from 'vue'
+import { useEntityItemFormPage, FormPage, useOrchestrator, RoleGrantsEditor } from '../../index.js'
 import InputText from 'primevue/inputtext'
-import AutoComplete from 'primevue/autocomplete'
-import Chip from 'primevue/chip'
-import type { PermissionRegistry } from '../PermissionRegistry'
+import {
+  inheritedGrants,
+  type InheritableRole,
+  type RoleComposition,
+  type RoleHierarchySource,
+} from '../roleGrants'
 
 /**
- * Role option for autocomplete
+ * What the form reads from the roles provider
  */
-interface RoleOption {
-  name: string
-  label: string
-  display: string
-}
-
-/**
- * Role data from roles provider
- */
-interface RoleData {
-  label?: string
-  [key: string]: unknown
-}
-
-/**
- * RolesProvider interface
- */
-interface RolesProviderInterface {
+interface RolesProviderInterface extends RoleHierarchySource {
   getRoles: () => string[]
-  getRole?: (name: string) => RoleData | null
+  getRole?: (name: string) => { label?: string } | null
+  getRoleMeta?: (name: string) => { label?: string; description?: string } | null
 }
 
 /**
  * Roles manager interface
  */
 interface RolesManager {
-  rolesProvider?: RolesProviderInterface
-}
-
-/**
- * Autocomplete search event
- */
-interface AutocompleteSearchEvent {
-  query?: string
-}
-
-/**
- * Autocomplete select event
- */
-interface AutocompleteSelectEvent {
-  value: RoleOption
+  rolesProvider?: RolesProviderInterface | null
 }
 
 /**
@@ -73,61 +49,27 @@ 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})`
-      }
-    })
+const provider = computed(() => manager?.rolesProvider ?? null)
+
+const roles = computed<InheritableRole[]>(() =>
+  (provider.value?.getRoles() ?? []).map((name: string) => {
+    const meta = provider.value?.getRoleMeta?.(name)
+    return { name, label: provider.value?.getRole?.(name)?.label || meta?.label || name, description: meta?.description }
+  })
+)
+
+const composition = computed<RoleComposition>({
+  get: () => {
+    const data = form.data.value as RoleFormData
+    return { inherits: data.inherits || [], permissions: data.permissions || [] }
+  },
+  set: (value: RoleComposition) => {
+    form.data.value.inherits = value.inherits
+    form.data.value.permissions = value.permissions
+  },
 })
 
-// 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
-}
+const inherited = computed(() => inheritedGrants(provider.value, composition.value.inherits))
 </script>
 
 <template>
@@ -156,56 +98,14 @@ function getRoleLabel(roleName: string): string {
           />
         </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 -->
+        <!-- Inherits + 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..."
+          <label class="font-medium">Permissions</label>
+          <RoleGrantsEditor
+            v-model="composition"
+            :roles="roles"
+            :inherited="inherited"
+            :self="(form.data.value as RoleFormData).name"
           />
         </div>
       </div>
@@ -224,53 +124,4 @@ function getRoleLabel(roleName: string): string {
   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/roleGrants.ts

@@ -0,0 +1,210 @@
+/**
+ * A role's composition, as RoleGrantsEditor draws it (#2313): which registered grants the role holds, and where
+ * each one comes from.
+ *
+ * Pure and judge-free. What inherited roles bring is given, never resolved here (the app's server may be the one
+ * that judges); wildcards are read with PermissionMatcher, `*` being one segment and `**` any number.
+ */
+import { PermissionMatcher } from './PermissionMatcher'
+
+/** A registry entry, or anything shaped like one (an app may pass its server's list). */
+export interface GrantDefinition {
+  key: string
+  namespace: string
+  action: string
+  label?: string
+  description?: string | null
+}
+
+/** A grant an inherited role brings, and the role that declares it. */
+export interface InheritedGrant {
+  permission: string
+  via: string
+}
+
+/** What RoleGrantsEditor edits: the role's own composition, never what it inherits. */
+export interface RoleComposition {
+  inherits: string[]
+  permissions: string[]
+}
+
+export interface InheritableRole {
+  name: string
+  label?: string
+  description?: string
+}
+
+export type GrantOrigin =
+  | { kind: 'none' }
+  | { kind: 'own' }
+  /** Covered by a wildcard the role holds. */
+  | { kind: 'wildcard'; via: string }
+  /** Brought by an inherited role. */
+  | { kind: 'inherited'; via: string }
+
+export interface GrantCell {
+  key: string
+  action: string
+  label: string
+  description: string | null
+  origin: GrantOrigin
+}
+
+/** One entity of the matrix: `entity:books`, or its ownership grants `entity-own:books`. */
+export interface GrantRow {
+  namespace: string
+  entity: string
+  ownRecords: boolean
+  /** `entity:books:*` */
+  wildcard: string
+  wildcardOrigin: GrantOrigin
+  /** By action; null where the entity registers no such grant. */
+  cells: Record<string, GrantCell | null>
+}
+
+/** Named grants of one namespace, as registered: `offers:debug:read` belongs to `offers:debug`, not `offers`. */
+export interface GrantGroup {
+  namespace: string
+  wildcard: string
+  wildcardOrigin: GrantOrigin
+  grants: GrantCell[]
+}
+
+/** A key of the role that is neither a registered grant nor a row or group wildcard. */
+export interface OtherGrant {
+  key: string
+  /** Registered grants it covers: 0 for a key the registry does not know. */
+  covers: number
+}
+
+export interface GrantsModel {
+  actions: string[]
+  rows: GrantRow[]
+  groups: GrantGroup[]
+  others: OtherGrant[]
+}
+
+const STANDARD_ACTIONS = ['read', 'list', 'create', 'update', 'delete']
+
+const isWildcard = (key: string) => key.includes('*')
+
+/** Where a grant comes from for the role: its own key first, then its wildcards, then what it inherits. */
+export function originOf(
+  key: string,
+  permissions: readonly string[],
+  inherited: readonly InheritedGrant[] = []
+): GrantOrigin {
+  if (permissions.includes(key)) return { kind: 'own' }
+  const wildcard = permissions.find((p) => isWildcard(p) && PermissionMatcher.matches(p, key))
+  if (wildcard) return { kind: 'wildcard', via: wildcard }
+  const brought = inherited.find((g) => PermissionMatcher.matches(g.permission, key))
+  if (brought) return { kind: 'inherited', via: brought.via }
+  return { kind: 'none' }
+}
+
+export function composeGrants(input: {
+  grants: readonly GrantDefinition[]
+  permissions: readonly string[]
+  inherited?: readonly InheritedGrant[]
+}): GrantsModel {
+  const { grants, permissions } = input
+  const inherited = input.inherited ?? []
+  const cellOf = (g: GrantDefinition): GrantCell => ({
+    key: g.key,
+    action: g.action,
+    label: g.label || g.key,
+    description: g.description ?? null,
+    origin: originOf(g.key, permissions, inherited),
+  })
+
+  const entityNamespaces = new Map<string, GrantDefinition[]>()
+  const namedNamespaces = new Map<string, GrantDefinition[]>()
+  for (const g of grants) {
+    const target = /^entity(-own)?:/.test(g.namespace) ? entityNamespaces : namedNamespaces
+    target.set(g.namespace, [...(target.get(g.namespace) ?? []), g])
+  }
+
+  const registeredActions = new Set<string>()
+  for (const list of entityNamespaces.values()) for (const g of list) registeredActions.add(g.action)
+  const actions = [
+    ...STANDARD_ACTIONS.filter((a) => registeredActions.has(a)),
+    ...[...registeredActions].filter((a) => !STANDARD_ACTIONS.includes(a)).sort(),
+  ]
+
+  const rows: GrantRow[] = [...entityNamespaces.entries()]
+    .map(([namespace, list]) => {
+      const cells: Record<string, GrantCell | null> = {}
+      for (const action of actions) {
+        const g = list.find((d) => d.action === action)
+        cells[action] = g ? cellOf(g) : null
+      }
+      const wildcard = `${namespace}:*`
+      return {
+        namespace,
+        entity: namespace.slice(namespace.indexOf(':') + 1),
+        ownRecords: namespace.startsWith('entity-own:'),
+        wildcard,
+        wildcardOrigin: originOf(wildcard, permissions, inherited),
+        cells,
+      }
+    })
+    .sort((a, b) => a.entity.localeCompare(b.entity) || Number(a.ownRecords) - Number(b.ownRecords))
+
+  const groups: GrantGroup[] = [...namedNamespaces.entries()]
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([namespace, list]) => ({
+      namespace,
+      wildcard: `${namespace}:*`,
+      wildcardOrigin: originOf(`${namespace}:*`, permissions, inherited),
+      grants: list.map(cellOf),
+    }))
+
+  const registered = new Set(grants.map((g) => g.key))
+  const shown = new Set([...rows.map((r) => r.wildcard), ...groups.map((g) => g.wildcard)])
+  const keys = grants.map((g) => g.key)
+  const others = [...new Set(permissions)]
+    .filter((p) => !registered.has(p) && !shown.has(p))
+    .map((key) => ({ key, covers: isWildcard(key) ? PermissionMatcher.expand(key, keys).length : 0 }))
+
+  return { actions, rows, groups, others }
+}
+
+/** The role's own keys with one added or removed; the others keep their order. */
+export function setGrant(permissions: readonly string[], key: string, on: boolean): string[] {
+  if (on) return permissions.includes(key) ? [...permissions] : [...permissions, key]
+  return permissions.filter((p) => p !== key)
+}
+
+/** What inheritedGrants needs from a roles provider: qdadm's RoleProvider has it. */
+export interface RoleHierarchySource {
+  getPermissions(role: string): string[]
+  getHierarchy(): Record<string, string[]>
+}
+
+/**
+ * What a role inherits, for apps whose front knows the roles (qdadm's own RoleProvider): each grant with the role
+ * that declares it, the nearest one first across a chain. An app whose server judges sends this list instead.
+ */
+export function inheritedGrants(
+  provider: RoleHierarchySource | null | undefined,
+  inherits: readonly string[]
+): InheritedGrant[] {
+  if (!provider) return []
+  const hierarchy = provider.getHierarchy() ?? {}
+  const visited = new Set<string>()
+  const known = new Set<string>()
+  const out: InheritedGrant[] = []
+  const queue = [...inherits]
+  while (queue.length > 0) {
+    const role = queue.shift()!
+    if (visited.has(role)) continue
+    visited.add(role)
+    for (const permission of provider.getPermissions(role) ?? []) {
+      if (known.has(permission)) continue
+      known.add(permission)
+      out.push({ permission, via: role })
+    }
+    queue.push(...(hierarchy[role] ?? []))
+  }
+  return out
+}