qdadm 0.31.0 → 0.34.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qdadm",
-  "version": "0.31.0",
+  "version": "0.34.0",
   "description": "Vue 3 framework for admin dashboards with PrimeVue",
   "author": "quazardous",
   "license": "MIT",
@@ -20,6 +20,7 @@
   },
   "exports": {
     ".": "./src/index.js",
+    "./auth": "./src/auth/index.js",
     "./composables": "./src/composables/index.js",
     "./components": "./src/components/index.js",
     "./editors": "./src/editors/index.js",

package/src/auth/SessionAuthAdapter.js

@@ -0,0 +1,254 @@
+/**
+ * SessionAuthAdapter - Base class for user authentication
+ *
+ * Applications extend this class to implement their authentication logic.
+ * The adapter handles user sessions: login, logout, token management.
+ *
+ * This is different from EntityAuthAdapter which handles entity-level permissions.
+ *
+ * @example
+ * ```js
+ * class MyAuthAdapter extends SessionAuthAdapter {
+ *   async login({ username, password }) {
+ *     const response = await api.post('/auth/login', { username, password })
+ *     this.setSession(response.token, response.user)
+ *     return { token: response.token, user: response.user }
+ *   }
+ *
+ *   logout() {
+ *     this.clearSession()
+ *   }
+ * }
+ * ```
+ *
+ * @abstract
+ */
+export class SessionAuthAdapter {
+  /**
+   * Internal session state
+   * @protected
+   */
+  _token = null
+  _user = null
+
+  /**
+   * Authenticate user with credentials
+   *
+   * @param {object} credentials - Login credentials
+   * @param {string} credentials.username - Username or email
+   * @param {string} credentials.password - Password
+   * @returns {Promise<{token: string, user: object}>} Session data
+   * @throws {Error} If authentication fails
+   *
+   * @example
+   * const { token, user } = await adapter.login({ username: 'admin', password: 'secret' })
+   */
+  async login(credentials) {
+    throw new Error('[SessionAuthAdapter] login() must be implemented by subclass')
+  }
+
+  /**
+   * End the current session
+   *
+   * Should clear all session data (tokens, user info).
+   * Called by AppLayout logout button and useAuth().logout()
+   */
+  logout() {
+    throw new Error('[SessionAuthAdapter] logout() must be implemented by subclass')
+  }
+
+  /**
+   * Check if user is currently authenticated
+   *
+   * @returns {boolean} True if user has valid session
+   *
+   * @example
+   * if (adapter.isAuthenticated()) {
+   *   // Show dashboard
+   * } else {
+   *   // Redirect to login
+   * }
+   */
+  isAuthenticated() {
+    throw new Error('[SessionAuthAdapter] isAuthenticated() must be implemented by subclass')
+  }
+
+  /**
+   * Get the current authentication token
+   *
+   * Used by API clients to include in request headers.
+   *
+   * @returns {string|null} JWT token or null if not authenticated
+   *
+   * @example
+   * const token = adapter.getToken()
+   * fetch('/api/data', {
+   *   headers: { Authorization: `Bearer ${token}` }
+   * })
+   */
+  getToken() {
+    throw new Error('[SessionAuthAdapter] getToken() must be implemented by subclass')
+  }
+
+  /**
+   * Get the current user object
+   *
+   * Returns user data from the session. The shape depends on your backend.
+   *
+   * @returns {object|null} User object or null if not authenticated
+   *
+   * @example
+   * const user = adapter.getUser()
+   * console.log(user.username, user.email, user.roles)
+   */
+  getUser() {
+    throw new Error('[SessionAuthAdapter] getUser() must be implemented by subclass')
+  }
+
+  /**
+   * Synchronous user getter (optional)
+   *
+   * Some implementations prefer a property instead of method.
+   * useAuth() supports both patterns.
+   *
+   * @type {object|null}
+   */
+  get user() {
+    return this.getUser()
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Helper methods for subclasses
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Set session data (helper for subclasses)
+   *
+   * @param {string} token - Authentication token
+   * @param {object} user - User object
+   * @protected
+   */
+  setSession(token, user) {
+    this._token = token
+    this._user = user
+  }
+
+  /**
+   * Clear session data (helper for subclasses)
+   *
+   * @protected
+   */
+  clearSession() {
+    this._token = null
+    this._user = null
+  }
+
+  /**
+   * Validate that the adapter is properly configured
+   *
+   * Called during bootstrap to catch configuration errors early.
+   *
+   * @throws {Error} If required methods are not implemented
+   */
+  static validate(adapter) {
+    const required = ['login', 'logout', 'isAuthenticated', 'getToken', 'getUser']
+    const missing = required.filter(method => typeof adapter[method] !== 'function')
+
+    if (missing.length > 0) {
+      throw new Error(
+        `[SessionAuthAdapter] Missing required methods: ${missing.join(', ')}\n` +
+        'Ensure your authAdapter implements all required methods or extends SessionAuthAdapter.'
+      )
+    }
+  }
+}
+
+/**
+ * LocalStorage-based SessionAuthAdapter implementation
+ *
+ * Ready-to-use adapter that stores session in localStorage.
+ * Extend and override login() to add your API call.
+ *
+ * @example
+ * ```js
+ * class MyAuthAdapter extends LocalStorageSessionAuthAdapter {
+ *   constructor() {
+ *     super('my_app_auth') // localStorage key
+ *   }
+ *
+ *   async login({ username, password }) {
+ *     const res = await fetch('/api/login', {
+ *       method: 'POST',
+ *       body: JSON.stringify({ username, password })
+ *     })
+ *     const data = await res.json()
+ *     this.setSession(data.token, data.user)
+ *     this.persist()
+ *     return data
+ *   }
+ * }
+ * ```
+ */
+export class LocalStorageSessionAuthAdapter extends SessionAuthAdapter {
+  /**
+   * @param {string} storageKey - localStorage key for session data
+   */
+  constructor(storageKey = 'qdadm_auth') {
+    super()
+    this._storageKey = storageKey
+    this._restore()
+  }
+
+  /**
+   * Restore session from localStorage on init
+   * @private
+   */
+  _restore() {
+    try {
+      const stored = localStorage.getItem(this._storageKey)
+      if (stored) {
+        const { token, user } = JSON.parse(stored)
+        this._token = token
+        this._user = user
+      }
+    } catch {
+      // Invalid stored data, ignore
+    }
+  }
+
+  /**
+   * Persist session to localStorage
+   * Call after login() to save session
+   * @protected
+   */
+  persist() {
+    if (this._token && this._user) {
+      localStorage.setItem(this._storageKey, JSON.stringify({
+        token: this._token,
+        user: this._user
+      }))
+    } else {
+      localStorage.removeItem(this._storageKey)
+    }
+  }
+
+  // Arrow functions to preserve `this` when used as callbacks
+  logout = () => {
+    this.clearSession()
+    localStorage.removeItem(this._storageKey)
+  }
+
+  isAuthenticated = () => {
+    return !!this._token
+  }
+
+  getToken = () => {
+    return this._token
+  }
+
+  getUser = () => {
+    return this._user
+  }
+}
+
+export default SessionAuthAdapter

package/src/auth/index.js

@@ -0,0 +1,10 @@
+/**
+ * Auth module - User session authentication
+ *
+ * For entity-level permissions, see entity/auth/EntityAuthAdapter
+ */
+
+export {
+  SessionAuthAdapter,
+  LocalStorageSessionAuthAdapter,
+} from './SessionAuthAdapter.js'

package/src/components/layout/AppLayout.vue

@@ -35,6 +35,7 @@ const route = useRoute()
 const app = useApp()
 const { navSections, isNavActive, sectionHasActiveItem, handleNavClick } = useNavigation()
 const { isAuthenticated, user, logout, authEnabled } = useAuth()
+const signals = inject('qdadmSignals', null)
 
 // LocalStorage key for collapsed sections state (namespaced by app)
 const STORAGE_KEY = computed(() => `${app.shortName.toLowerCase()}_nav_collapsed`)
@@ -150,6 +151,7 @@ const userSubtitle = computed(() => {
 
 function handleLogout() {
   logout()
+  signals?.emit('auth:logout', { reason: 'user' })
   router.push({ name: 'login' })
 }
 

package/src/components/pages/LoginPage.vue

@@ -90,11 +90,12 @@ const props = defineProps({
     default: ''
   },
   /**
-   * Emit business signal on login (requires orchestrator)
+   * Emit auth:login signal on successful login
+   * Required for debug bar auth tracking and other signal listeners
    */
   emitSignal: {
     type: Boolean,
-    default: false
+    default: true
   }
 })
 

package/src/composables/useAuth.js

@@ -8,7 +8,7 @@
  * For route guards or services, use authAdapter directly.
  *
  * Reactivity:
- * - Listens to auth:login, auth:logout, auth:impersonate signals
+ * - Listens to auth:login, auth:logout, auth:impersonate, auth:impersonate:stop signals
  * - User computed re-evaluates when these signals fire
  * - No polling or manual refresh needed
  *
@@ -54,6 +54,7 @@ export function useAuth() {
     cleanups.push(signals.on('auth:login', () => { authTick.value++ }))
     cleanups.push(signals.on('auth:logout', () => { authTick.value++ }))
     cleanups.push(signals.on('auth:impersonate', () => { authTick.value++ }))
+    cleanups.push(signals.on('auth:impersonate:stop', () => { authTick.value++ }))
   }
 
   // Cleanup signal subscriptions on unmount

package/src/composables/useFormPageBuilder.js

@@ -120,7 +120,13 @@ export function useFormPageBuilder(config = {}) {
   // Get EntityManager via orchestrator
   const orchestrator = inject('qdadmOrchestrator')
   if (!orchestrator) {
-    throw new Error('[qdadm] Orchestrator not provided. Make sure to use createQdadm() with entityFactory.')
+    throw new Error(
+      '[qdadm] Orchestrator not provided.\n' +
+      'Possible causes:\n' +
+      '1. Kernel not initialized - ensure createKernel().createApp() is called before mounting\n' +
+      '2. Component used outside of qdadm app context\n' +
+      '3. Missing entityFactory in Kernel options'
+    )
   }
   const manager = orchestrator.get(entity)
 

package/src/composables/useListPageBuilder.js

@@ -143,7 +143,13 @@ export function useListPageBuilder(config = {}) {
   // Get EntityManager via orchestrator
   const orchestrator = inject('qdadmOrchestrator')
   if (!orchestrator) {
-    throw new Error('[qdadm] Orchestrator not provided. Make sure to use createQdadm() with entityFactory.')
+    throw new Error(
+      '[qdadm] Orchestrator not provided.\n' +
+      'Possible causes:\n' +
+      '1. Kernel not initialized - ensure createKernel().createApp() is called before mounting\n' +
+      '2. Component used outside of qdadm app context\n' +
+      '3. Missing entityFactory in Kernel options'
+    )
   }
   const manager = orchestrator.get(entity)
 

package/src/debug/AuthCollector.js

@@ -39,8 +39,11 @@ export class AuthCollector extends Collector {
     this._ctx = null
     this._signalCleanups = []
     // Activity tracking for login/logout events
-    this._hasActivity = false
-    this._lastEvent = null // 'login' | 'logout' | null
+    // Keep recent events to show stacked (last N events)
+    this._recentEvents = [] // Array of { type: 'login'|'logout', timestamp: Date, seen: boolean }
+    this._maxEvents = 5
+    this._eventTtl = options.eventTtl ?? 60000 // Events expire after 60s by default
+    this._expiryTimer = null
   }
 
   /**
@@ -70,19 +73,81 @@ export class AuthCollector extends Collector {
     }
 
     // Listen to auth events and track activity
-    const loginCleanup = signals.on('auth:login', () => {
-      this._hasActivity = true
-      this._lastEvent = 'login'
-      this.notifyChange()
+    const loginCleanup = signals.on('auth:login', (event) => {
+      // QuarKernel wraps payload in KernelEvent - extract data from event.data
+      const data = event?.data || event
+      const user = data?.user || this._authAdapter?.getUser?.()
+      this._addEvent('login', { user })
     })
     this._signalCleanups.push(loginCleanup)
 
     const logoutCleanup = signals.on('auth:logout', () => {
-      this._hasActivity = true
-      this._lastEvent = 'logout'
-      this.notifyChange()
+      this._addEvent('logout')
     })
     this._signalCleanups.push(logoutCleanup)
+
+    const impersonateCleanup = signals.on('auth:impersonate', (payload) => {
+      this._addEvent('impersonate', payload)
+    })
+    this._signalCleanups.push(impersonateCleanup)
+
+    const impersonateStopCleanup = signals.on('auth:impersonate:stop', (payload) => {
+      this._addEvent('impersonate-stop', payload)
+    })
+    this._signalCleanups.push(impersonateStopCleanup)
+  }
+
+  /**
+   * Add an auth event to the recent events list
+   * @param {string} type - 'login' | 'logout' | 'impersonate' | 'impersonate-stop'
+   * @param {object} [data] - Optional event data (e.g., { user } for impersonate)
+   * @private
+   */
+  _addEvent(type, data = null) {
+    this._recentEvents.unshift({
+      type,
+      timestamp: new Date(),
+      id: Date.now(), // Unique ID for Vue key
+      seen: false,
+      data
+    })
+    // Keep only last N events
+    if (this._recentEvents.length > this._maxEvents) {
+      this._recentEvents.pop()
+    }
+    this._scheduleExpiry()
+    this.notifyChange()
+  }
+
+  /**
+   * Schedule event expiry check
+   * @private
+   */
+  _scheduleExpiry() {
+    if (this._expiryTimer) return // Already scheduled
+    this._expiryTimer = setTimeout(() => {
+      this._expireOldEvents()
+    }, this._eventTtl)
+  }
+
+  /**
+   * Remove expired events
+   * @private
+   */
+  _expireOldEvents() {
+    this._expiryTimer = null
+    const now = Date.now()
+    const before = this._recentEvents.length
+    this._recentEvents = this._recentEvents.filter(
+      e => (now - e.timestamp.getTime()) < this._eventTtl
+    )
+    if (this._recentEvents.length < before) {
+      this.notifyChange()
+    }
+    // Reschedule if still have events
+    if (this._recentEvents.length > 0) {
+      this._scheduleExpiry()
+    }
   }
 
   /**
@@ -90,6 +155,10 @@ export class AuthCollector extends Collector {
    * @protected
    */
   _doUninstall() {
+    if (this._expiryTimer) {
+      clearTimeout(this._expiryTimer)
+      this._expiryTimer = null
+    }
     for (const cleanup of this._signalCleanups) {
       if (typeof cleanup === 'function') cleanup()
     }
@@ -99,11 +168,11 @@ export class AuthCollector extends Collector {
   }
 
   /**
-   * Get badge - show 1 if there's unseen auth activity
-   * @returns {number} 1 if activity unseen, 0 otherwise
+   * Get badge - show count of unseen auth events
+   * @returns {number} Number of unseen events
    */
   getBadge() {
-    return this._hasActivity ? 1 : 0
+    return this._recentEvents.filter(e => !e.seen).length
   }
 
   /**
@@ -111,24 +180,41 @@ export class AuthCollector extends Collector {
    * @returns {boolean}
    */
   hasActivity() {
-    return this._hasActivity
+    return this._recentEvents.some(e => !e.seen)
   }
 
   /**
-   * Get the last auth event type
+   * Get all recent auth events (newest first)
+   * @returns {Array<{type: string, timestamp: Date, id: number, seen: boolean}>}
+   */
+  getRecentEvents() {
+    return this._recentEvents
+  }
+
+  /**
+   * Get the last auth event type (for backward compatibility)
    * @returns {string|null} 'login' | 'logout' | null
    */
   getLastEvent() {
-    return this._lastEvent
+    return this._recentEvents[0]?.type || null
   }
 
   /**
-   * Mark activity as seen (clear activity state)
+   * Mark all events as seen (badge resets but events stay visible)
    * Note: Does not call notifyChange() to avoid re-render loop
    */
   markSeen() {
-    this._hasActivity = false
-    this._lastEvent = null
+    for (const event of this._recentEvents) {
+      event.seen = true
+    }
+  }
+
+  /**
+   * Clear all events (for explicit dismissal)
+   */
+  clearEvents() {
+    this._recentEvents = []
+    this.notifyChange()
   }
 
   /**

package/src/debug/Collector.js

@@ -179,10 +179,11 @@ export class Collector {
 
   /**
    * Get all entries
+   * Returns a shallow copy to trigger Vue reactivity when used in computed
    * @returns {Array<object>} All recorded entries
    */
   getEntries() {
-    return this.entries
+    return [...this.entries]
   }
 
   /**

package/src/debug/EntitiesCollector.js

@@ -219,10 +219,11 @@ export class EntitiesCollector extends Collector {
       idField: manager.idField,
 
       // Storage info
+      // Prefer instance capabilities (may include requiresAuth) over static ones
       storage: {
         type: storage?.constructor?.name || 'None',
         endpoint: storage?.endpoint || storage?._endpoint || null,
-        capabilities: storage?.constructor?.capabilities || {}
+        capabilities: storage?.capabilities || storage?.constructor?.capabilities || {}
       },
 
       // Cache info
@@ -373,4 +374,30 @@ export class EntitiesCollector extends Collector {
   markEntitySeen(entityName) {
     this._activeEntities.delete(entityName)
   }
+
+  /**
+   * Test fetch data from a specific entity
+   * Used to test auth protection - will throw 401 if not authenticated
+   * @param {string} entityName - Entity name
+   * @returns {Promise<{success: boolean, count?: number, error?: string, status?: number}>}
+   */
+  async testFetch(entityName) {
+    if (!this._orchestrator) {
+      return { success: false, error: 'No orchestrator' }
+    }
+    try {
+      const manager = this._orchestrator.get(entityName)
+      const result = await manager.storage.list({ page: 1, page_size: 1 })
+      return {
+        success: true,
+        count: result.total ?? result.items?.length ?? 0
+      }
+    } catch (e) {
+      return {
+        success: false,
+        error: e.message,
+        status: e.status
+      }
+    }
+  }
 }