@quazardous/qdadm 2.23.0 → 2.24.0

package/package.json

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

package/src/entity/EntityManager.ts

@@ -654,7 +654,8 @@ export class EntityManager<T extends EntityRecord = EntityRecord> {
   }
 
   /**
-   * Check if entity is system-provided (roles, users)
+   * Whether this entity is one the framework provides (roles, users). Owned
+   * by qdadm — see `EntityManagerOptions.system`.
    */
   get system(): boolean {
     return this._system

package/src/entity/EntityManager.types.ts

@@ -271,6 +271,15 @@ export interface EntityManagerOptions<T extends EntityRecord = EntityRecord> {
    * drop the stale cache but leave the screen alone until the user asks.
    */
   live?: LiveEntityPolicy
+  /**
+   * Marks an entity the framework provides (`roles`, `users`). Owned by
+   * qdadm: set by its system managers (`RolesManager`, `UsersManager`), not
+   * by applications. Behaviour may be attached to it in any release.
+   *
+   * To keep a system entity on your own storage, use its manager with your
+   * storage — `new RolesManager({ storage })` — rather than setting the flag
+   * on a plain entity.
+   */
   system?: boolean
   scopeWhitelist?: string[] | null
   isOwn?: ((record: T, user: AuthUser) => boolean) | null

package/src/entity/auth/SecurityChecker.ts

@@ -26,8 +26,8 @@ export interface GrantJudgeContext {
    *
    * `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`.
+   * framework's own namespaces. Read the keys when you fetch (on `kernel:ready`
+   * or `auth:login`), not in `install`.
    */
   permissionRegistry?: { getKeys(): string[] }
 }
@@ -44,12 +44,29 @@ export interface GrantJudgeContext {
  *   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.
+ * `isGranted` is called synchronously on every check, so answer from memory,
+ * and emit `security:changed` when answers change.
+ *
+ * A judge whose answers come from a request cannot have them before the first
+ * navigation: it starts inside `createApp()`. Such a judge implements `ready()`
+ * (#2412), and the route guard waits for it instead of deciding early.
  */
 export interface GrantJudge {
   isGranted(attribute: string, subject: unknown, user: AuthUser): boolean | undefined
   install?(ctx: GrantJudgeContext): void
+  /**
+   * Settles once the answers for the current user are loaded (#2412).
+   *
+   * Return the promise of the load in progress — the one started on
+   * `kernel:ready`, or the new one after `auth:login` — so the route guard
+   * waits for this user's answers, not an earlier user's. A resolved promise
+   * means "decide now". A rejection, or no settling within
+   * `security.readyTimeoutMs`, denies the navigation: the unknown is never
+   * allowed, only no longer decided before the answers can exist.
+   *
+   * Optional: a judge that answers from memory from the start needs none.
+   */
+  ready?(): Promise<void>
 }
 
 /**

package/src/kernel/Kernel.registries.ts

@@ -406,13 +406,14 @@ export function applyRegistryMethods(KernelClass: { prototype: Kernel }): void {
     this._warnUnknownKeys(
       'security.',
       security,
-      new Set(['role_hierarchy', 'role_permissions', 'role_labels', 'entity_permissions', 'rolesProvider', 'grant']),
+      new Set(['role_hierarchy', 'role_permissions', 'role_labels', 'entity_permissions', 'rolesProvider', 'grant', 'readyTimeoutMs']),
       {
         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",
+        readyTimeoutMs: 'the route guard waits the default 10 s for grant.ready()',
       }
     )
   }

package/src/kernel/Kernel.routing.ts

@@ -15,6 +15,28 @@ type Self = Kernel
 /**
  * Patch Kernel prototype with routing-related methods.
  */
+/**
+ * `judge.ready()`, bounded (#2412): a judge that never settles must not hold a
+ * navigation forever. A synchronous throw from `ready()` counts as a rejection.
+ */
+function waitForJudge(judge: { ready(): Promise<void> }, timeoutMs: number): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error(`no answer within ${timeoutMs} ms`)), timeoutMs)
+    Promise.resolve()
+      .then(() => judge.ready())
+      .then(
+        () => {
+          clearTimeout(timer)
+          resolve()
+        },
+        (e: unknown) => {
+          clearTimeout(timer)
+          reject(e instanceof Error ? e : new Error(String(e)))
+        }
+      )
+  })
+}
+
 export function applyRoutingMethods(KernelClass: { prototype: Kernel }): void {
   const proto = KernelClass.prototype
 
@@ -230,14 +252,17 @@ export function applyRoutingMethods(KernelClass: { prototype: Kernel }): void {
       // declared before its manager loads) — allow. This is the ONLY
       // allowed pass-through; a failing access check must fail CLOSED,
       // not silently allow (#1190).
-      if (entity && this.orchestrator && this.orchestrator.isRegistered(entity)) {
+      const orchestrator = this.orchestrator
+      if (!entity || !orchestrator || !orchestrator.isRegistered(entity)) return
+
+      const checkEntity = (): { path: string } | undefined => {
         try {
-          const manager = this.orchestrator.get(entity)
+          const manager = orchestrator.get(entity)
           if (manager && !manager.canRead()) {
             console.warn(
               `[qdadm] Access denied to ${to.path} (entity: ${entity})`
             )
-            this.orchestrator.toast.error(
+            orchestrator.toast.error(
               'Access Denied',
               `You don't have permission to access ${manager.labelPlural || entity}`,
               'Kernel'
@@ -256,7 +281,23 @@ export function applyRoutingMethods(KernelClass: { prototype: Kernel }): void {
           )
           return { path: '/' }
         }
+        return undefined
       }
+
+      // A judge whose answers come from a request cannot have them yet on the
+      // first navigation, which starts inside createApp() (#2412). Its cache
+      // miss would fall through to an empty role matrix and read as a refusal:
+      // wait for its answers instead of deciding early. Still fail closed — a
+      // judge that rejects or never settles denies.
+      const judge = this.securityChecker?.grant
+      if (typeof judge?.ready !== 'function') return checkEntity()
+      const timeoutMs = this.options.security?.readyTimeoutMs ?? 10_000
+      return waitForJudge(judge as { ready(): Promise<void> }, timeoutMs).then(checkEntity, (reason: Error) => {
+        console.error(
+          `[qdadm] security.grant never became ready for ${to.path} (entity: ${entity}): ${reason.message} — denying navigation`
+        )
+        return { path: '/' }
+      })
     })
   }
 

package/src/kernel/Kernel.types.ts

@@ -105,6 +105,11 @@ export interface SecurityConfig {
    * throws denies. See docs/security.md.
    */
   grant?: GrantJudge
+  /**
+   * How long the route guard waits for `grant.ready()` before denying (#2412).
+   * Default 10000 ms. Only used when the judge implements `ready()`.
+   */
+  readyTimeoutMs?: number
 }
 
 /**

package/src/security/RolesManager.ts

@@ -40,6 +40,22 @@ interface EntityManagerInstance {
   }
 }
 
+/**
+ * The `roles` system entity.
+ *
+ * It is a system entity because this manager makes it one — apps do not set
+ * `system` themselves. To keep roles behind your own API, give it your
+ * storage; it stays a system entity:
+ *
+ * ```ts
+ * ctx.entity('roles', new RolesManager({ storage: myApiStorage }))
+ * ```
+ *
+ * Two things change compared with a plain entity, and both are deliberate:
+ * every `can*` goes through ONE permission (`adminPermission`), and `fields`
+ * / `idField` assume qdadm's shape (`name`, `label`, `permissions`,
+ * `inherits`) — override them when your API serves another one.
+ */
 export class RolesManager extends EntityManager<RoleRecord> {
   private _rolesProvider: RoleProvider | null
   private _permissionRegistry: PermissionRegistry | null
@@ -128,8 +144,12 @@ export class RolesManager extends EntityManager<RoleRecord> {
   canDelete(item?: RoleRecord | null): boolean {
     if (!this._isAdmin()) return false
     if (item) {
-      // Protected system roles cannot be deleted
-      return !RolesManager.PROTECTED_ROLES.includes(item.name)
+      // Protected system roles cannot be deleted. The role code is `name` in qdadm's shape, but an
+      // app whose API keys roles differently overrides `idField` (#2406): read both, or the guard
+      // silently stops matching.
+      const record = item as unknown as Record<string, unknown>
+      const codes = [record.name, record[this.idField]]
+      return !codes.some((code) => typeof code === 'string' && RolesManager.PROTECTED_ROLES.includes(code))
     }
     return true
   }