@quazardous/qdadm 2.20.0 → 2.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quazardous/qdadm",
-  "version": "2.20.0",
+  "version": "2.21.0",
   "description": "Vue 3 framework for admin dashboards with PrimeVue",
   "author": "quazardous",
   "license": "MIT",

package/src/entity/auth/SecurityChecker.ts

@@ -15,6 +15,43 @@ export interface RoleProvider {
   readonly canPersist: boolean
 }
 
+/**
+ * What an application's judge receives at install time (#2225).
+ */
+export interface GrantJudgeContext {
+  orchestrator?: unknown
+  signals?: unknown
+  /**
+   * The live permission registry — a REFERENCE, not a snapshot.
+   *
+   * `install` runs while the Kernel is still being built, before modules
+   * register their entities, so `getKeys()` called here returns only the
+   * framework's own namespaces. Read the keys when you pre-warm (after login,
+   * before mount), not in `install`.
+   */
+  permissionRegistry?: { getKeys(): string[] }
+}
+
+/**
+ * An application-provided judgement of permissions (#2225).
+ *
+ * For apps whose backend decides who may do what: the judge answers from its
+ * own cache instead of qdadm's role matrix. It is consulted FIRST, for roles
+ * and permissions alike.
+ *
+ * - `true` / `false` is the verdict.
+ * - Anything else (`undefined`, `null`, a cache miss) falls through to the
+ *   built-in judgement, which stays the default.
+ * - A judge that THROWS denies — see `SecurityChecker._judge`.
+ *
+ * `isGranted` is called synchronously on every check, so answer from memory.
+ * Fetch in bulk beforehand and emit `security:changed` when answers change.
+ */
+export interface GrantJudge {
+  isGranted(attribute: string, subject: unknown, user: AuthUser): boolean | undefined
+  install?(ctx: GrantJudgeContext): void
+}
+
 /**
  * SecurityChecker constructor options
  */
@@ -22,6 +59,8 @@ export interface SecurityCheckerOptions {
   rolesProvider?: RoleProvider
   roleHierarchy?: RoleHierarchy | RoleHierarchyConfig
   rolePermissions?: Record<string, string[]>
+  /** Application-provided judgement, consulted first (#2225). */
+  grant?: GrantJudge
   getCurrentUser: () => AuthUser | null
 }
 
@@ -32,6 +71,8 @@ export interface SecurityCheckerConfig {
   rolesProvider?: RoleProvider
   role_hierarchy?: RoleHierarchyConfig
   role_permissions?: Record<string, string[]>
+  /** Application-provided judgement, consulted first (#2225). */
+  grant?: GrantJudge
   getCurrentUser: () => AuthUser | null
 }
 
@@ -55,8 +96,12 @@ export class SecurityChecker {
   readonly getCurrentUser: () => AuthUser | null
   /** Roles already warned about (warn-once, #1388) */
   protected _warnedRoles = new Set<string>()
+  /** Application-provided judgement, consulted before the role matrix (#2225) */
+  protected _grant: GrantJudge | null
+  /** Attributes whose judge already threw (report-once) */
+  protected _judgeFailures = new Set<string>()
 
-  constructor({ rolesProvider, roleHierarchy, rolePermissions, getCurrentUser }: SecurityCheckerOptions) {
+  constructor({ rolesProvider, roleHierarchy, rolePermissions, grant, getCurrentUser }: SecurityCheckerOptions) {
     if (rolesProvider) {
       this._rolesProvider = rolesProvider
     } else {
@@ -75,6 +120,12 @@ export class SecurityChecker {
     }
 
     this.getCurrentUser = getCurrentUser
+    this._grant = grant ?? null
+  }
+
+  /** The application's judge, when one is configured (#2225). */
+  get grant(): GrantJudge | null {
+    return this._grant
   }
 
   /**
@@ -108,10 +159,15 @@ export class SecurityChecker {
    *
    * This is the main contract method, similar to Symfony's isGranted().
    */
-  isGranted(attribute: string, _subject: unknown = null): boolean {
+  isGranted(attribute: string, subject: unknown = null): boolean {
     const user = this.getCurrentUser()
     if (!user) return false
 
+    // 0. The application's own judgement comes first (#2225). A boolean is a
+    //    verdict; anything else falls through to the built-in matrix below.
+    const verdict = this._judge(attribute, subject, user)
+    if (verdict !== undefined) return verdict
+
     // 1. Check if it's a role (ROLE_*)
     if (attribute.startsWith('ROLE_')) {
       return this.roleHierarchy.isGrantedRole(user.roles || [user.role || ''], attribute)
@@ -122,6 +178,34 @@ export class SecurityChecker {
     return PermissionMatcher.any(userPerms, attribute)
   }
 
+  /**
+   * Ask the application's judge, if any.
+   *
+   * A judge that THROWS denies. Falling through to the built-in matrix would
+   * quietly substitute a different authority for the one the app configured,
+   * and failing open would grant whatever the backend never got to answer —
+   * the worst direction a security check can fail in (the rule the route
+   * guard already follows, #1190). Reported once per attribute.
+   */
+  protected _judge(attribute: string, subject: unknown, user: AuthUser): boolean | undefined {
+    if (!this._grant) return undefined
+    let answer: unknown
+    try {
+      answer = this._grant.isGranted(attribute, subject, user)
+    } catch (error) {
+      if (!this._judgeFailures.has(attribute)) {
+        this._judgeFailures.add(attribute)
+        console.error(
+          `[qdadm] security.grant threw while judging "${attribute}" — DENIED. ` +
+            `A failing judge denies rather than falling back to the role matrix.`,
+          error
+        )
+      }
+      return false
+    }
+    return typeof answer === 'boolean' ? answer : undefined
+  }
+
   /**
    * Get all permissions for a user (resolved from roles + user overrides)
    */
@@ -203,6 +287,7 @@ export function createSecurityChecker(config: SecurityCheckerConfig): SecurityCh
   if (config.rolesProvider) {
     return new SecurityChecker({
       rolesProvider: config.rolesProvider,
+      grant: config.grant,
       getCurrentUser: config.getCurrentUser,
     })
   }
@@ -213,6 +298,7 @@ export function createSecurityChecker(config: SecurityCheckerConfig): SecurityCh
       role_hierarchy: config.role_hierarchy || {},
       role_permissions: config.role_permissions || {},
     }),
+    grant: config.grant,
     getCurrentUser: config.getCurrentUser,
   })
 }

package/src/entity/auth/index.ts

@@ -23,6 +23,8 @@ export type {
   RoleProvider,
   SecurityCheckerOptions,
   SecurityCheckerConfig,
+  GrantJudge,
+  GrantJudgeContext,
 } from './SecurityChecker'
 
 // Implementations

package/src/kernel/Kernel.auth.ts

@@ -120,11 +120,15 @@ export function applyAuthMethods(KernelClass: { prototype: Kernel }): void {
    */
   proto._setupAuthInvalidation = function (this: Self): void {
     const debug = this.options.debug ?? false
+    // `security:changed` (#2225) rides the same path: nothing on screen reads
+    // permissions reactively (canCreate, menu filtering and the route guard
+    // all ask synchronously), so a remount is what makes new answers show.
     const authSignals = [
       'auth:login',
       'auth:logout',
       'auth:impersonate',
       'auth:impersonate:stop',
+      'security:changed',
     ]
 
     for (const signal of authSignals) {

package/src/kernel/Kernel.registries.ts

@@ -141,6 +141,15 @@ export function applyRegistryMethods(KernelClass: { prototype: Kernel }): void {
       )
     }
 
+    // A `grant` that cannot judge would be silently skipped, leaving the role
+    // matrix to decide alone while the app believes its backend does (#2225).
+    if (security.grant && typeof security.grant.isGranted !== 'function') {
+      throw new Error(
+        '[qdadm] security.grant must provide isGranted(attribute, subject, user). ' +
+          'Without it the application judgement would be skipped and the role matrix would decide alone.'
+      )
+    }
+
     let rolesProvider = security.rolesProvider
     if (!rolesProvider && (security.role_permissions || security.role_hierarchy)) {
       rolesProvider = new StaticRoleProvider({
@@ -152,6 +161,7 @@ export function applyRegistryMethods(KernelClass: { prototype: Kernel }): void {
 
     this.securityChecker = createSecurityChecker({
       rolesProvider: rolesProvider || undefined,
+      grant: security.grant,
       getCurrentUser: () =>
         (entityAuthAdapter as EntityAuthAdapter | null)?.getCurrentUser?.() || null,
     })
@@ -165,14 +175,22 @@ export function applyRegistryMethods(KernelClass: { prototype: Kernel }): void {
       adapter.setSecurityChecker(this.securityChecker)
     }
 
+    // One context for both installers. `permissionRegistry` lets a provider or
+    // a judge pre-warm in one batch (#2225) — but modules register their
+    // entities AFTER this point, so the keys must be read at fetch time, not
+    // inside install().
+    const ctx = {
+      orchestrator: this.orchestrator,
+      signals: this.signals,
+      permissionRegistry: this.permissionRegistry,
+    }
     if (rolesProvider?.install) {
-      const ctx = {
-        orchestrator: this.orchestrator,
-        signals: this.signals,
-      }
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       rolesProvider.install(ctx as any)
     }
+    if (security.grant?.install) {
+      security.grant.install(ctx)
+    }
   }
 
   /**
@@ -388,12 +406,13 @@ export function applyRegistryMethods(KernelClass: { prototype: Kernel }): void {
     this._warnUnknownKeys(
       'security.',
       security,
-      new Set(['role_hierarchy', 'role_permissions', 'role_labels', 'entity_permissions', 'rolesProvider']),
+      new Set(['role_hierarchy', 'role_permissions', 'role_labels', 'entity_permissions', 'rolesProvider', 'grant']),
       {
         role_hierarchy: 'roles will not inherit from one another',
         role_permissions: 'no role will carry any permission',
         entity_permissions: 'per-entity permissions will not be generated',
         rolesProvider: "the current user's roles will not be resolved",
+        grant: "the application's judgement will not be consulted — the role matrix decides alone",
       }
     )
   }

package/src/kernel/Kernel.types.ts

@@ -10,6 +10,7 @@ import type { RoutesConfig } from './EventRouter'
 import type { EntityManager } from '../entity/EntityManager'
 import type { EntityAuthAdapter } from '../entity/auth/EntityAuthAdapter'
 import type { RoleProvider } from '../security/RolesProvider'
+import type { GrantJudge } from '../entity/auth/SecurityChecker'
 import type { I18nOptions } from '../i18n/types'
 import type { ApiClientSource } from '../api/apiClient'
 import type { RouteStatePersister } from '../routeState'
@@ -98,7 +99,12 @@ export interface SecurityConfig {
   role_permissions?: Record<string, string[]>
   role_labels?: Record<string, string>
   entity_permissions?: boolean | string[]
-  rolesProvider?: RoleProvider
+  rolesProvider?: RoleProvider  /**
+   * Application-provided judgement (#2225), consulted before the role matrix.
+   * `true`/`false` is the verdict, anything else falls through; a judge that
+   * throws denies. See docs/security.md.
+   */
+  grant?: GrantJudge
 }
 
 /**

package/src/kernel/SignalBus.ts

@@ -43,6 +43,12 @@ export const SIGNALS = {
   AUTH_LOGOUT: 'auth:logout',
   AUTH_EXPIRED: 'auth:expired', // Emitted on 401/403 API responses
 
+  // Security signals
+  // The application's permission answers changed — every screen re-evaluates
+  // (#2225). Emit it only when an answer actually differs: it remounts the app,
+  // which discards unsaved form state.
+  SECURITY_CHANGED: 'security:changed',
+
   // API error signals
   API_ERROR: 'api:error', // Emitted on any API error { status, message, url }
 } as const

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/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/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
 }