@quazardous/qdadm 1.19.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 quazardous
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+# qdadm
+
+**Vue 3 admin framework. PrimeVue. Zero boilerplate.**
+
+Quick start: [../../README.md](../../README.md) (5 min tutorial)
+
+Concepts & patterns: [QDADM_CREDO.md](QDADM_CREDO.md)
+
+Changelog: [../../CHANGELOG.md](../../CHANGELOG.md)
+
+## Installation
+
+```bash
+npm install @quazardous/qdadm primevue @primeuix/themes
+```
+
+## Exports
+
+```js
+// Core
+import { Kernel, EntityManager } from '@quazardous/qdadm'
+
+// Storage backends
+import { MockApiStorage, ApiStorage, SdkStorage } from '@quazardous/qdadm'
+
+// Auth
+import { SessionAuthAdapter, LocalStorageSessionAuthAdapter } from '@quazardous/qdadm'
+
+// Security (permissions, roles)
+import { SecurityChecker, PermissionMatcher, PermissionRegistry } from '@quazardous/qdadm/security'
+import { PersistableRoleProvider, createLocalStorageRolesProvider } from '@quazardous/qdadm/security'
+
+// Composables
+import { useForm, useBareForm, useListPageBuilder } from '@quazardous/qdadm/composables'
+
+// Components
+import { ListPage, PageLayout, AppLayout, FormField, FormActions } from '@quazardous/qdadm/components'
+
+// Module system
+import { KernelContext } from '@quazardous/qdadm/module'
+
+// Styles
+import '@quazardous/qdadm/styles'
+```
+
+## ctx.crud() - Route Helper
+
+Register CRUD routes + navigation in one call:
+
+```js
+class BooksModule extends Module {
+  async connect(ctx) {
+    ctx.entity('books', { ... })
+
+    // Full CRUD with single form
+    ctx.crud('books', {
+      list: () => import('./pages/BookList.vue'),
+      form: () => import('./pages/BookForm.vue')  // create + edit
+    }, {
+      nav: { section: 'Library', icon: 'pi pi-book' }
+    })
+
+    // List only (read-only entity)
+    ctx.crud('settings', {
+      list: () => import('./pages/SettingsPage.vue')
+    }, { nav: { section: 'Config', icon: 'pi pi-cog' } })
+  }
+}
+```
+
+Auto-generates: routes, route family, nav item. Use `ctx.routes()` for custom pages.
+
+## SdkStorage
+
+Adapter for generated SDK clients (hey-api, openapi-generator, etc.):
+
+```js
+import { SdkStorage } from '@quazardous/qdadm'
+
+const storage = new SdkStorage({
+  sdk,
+  methods: {
+    list: 'getApiBooks',
+    get: 'getApiBooksById',
+    create: 'postApiBooks',
+    update: 'patchApiBooksById',
+    delete: 'deleteApiBooksById'
+  }
+})
+```
+
+Options: `transformRequest`, `transformResponse`, `responseFormat`, `clientSidePagination`.
+
+## Documentation
+
+| Doc | Purpose |
+|-----|---------|
+| [QDADM_CREDO](QDADM_CREDO.md) | Philosophy, patterns, concepts |
+| [Architecture](../../docs/architecture.md) | PAC pattern, layers |
+| [Extension](../../docs/extension.md) | Hooks, signals, zones |
+
+## Peer Dependencies
+
+- vue ^3.3.0
+- vue-router ^4.0.0
+- primevue ^4.0.0
+- pinia ^2.0.0
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,101 @@
+{
+  "name": "@quazardous/qdadm",
+  "version": "1.19.3",
+  "description": "Vue 3 framework for admin dashboards with PrimeVue",
+  "author": "quazardous",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/quazardous/qdadm.git"
+  },
+  "homepage": "https://github.com/quazardous/qdadm#readme",
+  "bugs": {
+    "url": "https://github.com/quazardous/qdadm/issues"
+  },
+  "type": "module",
+  "main": "src/index.ts",
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "type-check": "vue-tsc --noEmit",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "format": "prettier --write src/",
+    "build:types": "vue-tsc --declaration --emitDeclarationOnly --outDir dist/types"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./auth": "./src/auth/index.ts",
+    "./security": "./src/security/index.ts",
+    "./composables": "./src/composables/index.ts",
+    "./components": "./src/components/index.ts",
+    "./editors": "./src/editors/index.ts",
+    "./module": "./src/module/index.ts",
+    "./utils": "./src/utils/index.ts",
+    "./modules/debug": "./src/modules/debug/index.ts",
+    "./styles": "./src/styles/index.scss",
+    "./styles/variables": "./src/styles/_variables.scss",
+    "./gen": "./src/gen/index.ts",
+    "./gen/vite-plugin": "./src/gen/vite-plugin.ts",
+    "./vite-plugin-debug": "./src/vite/qdadmDebugPlugin.ts"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@quazardous/qdcore": "^0.2.1",
+    "@quazardous/qddebug": "^0.2.1",
+    "@quazardous/quarkernel": "^2.1.0",
+    "pluralize": "^8.0.0",
+    "yaml": "^2.8.4"
+  },
+  "peerDependencies": {
+    "pinia": "^2.0.0 || ^3.0.0",
+    "primevue": "^4.0.0",
+    "vite": "^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0",
+    "vue": "^3.3.0",
+    "vue-router": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vanilla-jsoneditor": {
+      "optional": true
+    },
+    "vite": {
+      "optional": true
+    }
+  },
+  "optionalDependencies": {
+    "vanilla-jsoneditor": "^0.23.0"
+  },
+  "keywords": [
+    "vue",
+    "vue3",
+    "admin",
+    "dashboard",
+    "framework",
+    "primevue",
+    "crud",
+    "entity-manager"
+  ],
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@types/node": "^25.0.6",
+    "@vitejs/plugin-vue": "^6.0.0",
+    "@vue/test-utils": "^2.4.6",
+    "@vue/tsconfig": "^0.8.1",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.4",
+    "eslint-plugin-vue": "^10.6.2",
+    "globals": "^17.0.0",
+    "jsdom": "^25.0.1",
+    "prettier": "^3.7.4",
+    "sass": "^1.97.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.52.0",
+    "vitest": "^2.1.8",
+    "vue-tsc": "^3.2.2"
+  }
+}

package/src/assets/logo.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100" width="100" height="100">
+  <polygon points="50,5 93,27.5 93,72.5 50,95 7,72.5 7,27.5" fill="#1E3A8A"/>
+  <text x="48" y="50" text-anchor="middle" dominant-baseline="central" font-family="system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif" font-size="58" font-weight="800" letter-spacing="-4">
+    <tspan fill="#60A5FA">Q</tspan><tspan fill="#93C5FD">D</tspan>
+  </text>
+</svg>

package/src/auth/SessionAuthAdapter.ts

@@ -0,0 +1,459 @@
+/**
+ * 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
+ * ```ts
+ * class MyAuthAdapter extends SessionAuthAdapter {
+ *   async login({ username, password }: LoginCredentials) {
+ *     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
+ */
+
+import type { SignalBus } from '../kernel/SignalBus'
+
+/**
+ * Login credentials interface
+ */
+export interface LoginCredentials {
+  username: string
+  password: string
+  [key: string]: unknown
+}
+
+/**
+ * Session data returned from login
+ */
+export interface SessionData<TUser = AuthUser> {
+  token: string
+  user: TUser
+}
+
+/**
+ * Generic user object interface
+ */
+export interface AuthUser {
+  id?: string | number
+  username?: string
+  email?: string
+  name?: string
+  roles?: string[]
+  [key: string]: unknown
+}
+
+/**
+ * Interface for session authentication adapters
+ */
+export interface ISessionAuthAdapter<TUser = AuthUser> {
+  login(credentials: LoginCredentials): Promise<SessionData<TUser>>
+  logout(): void
+  isAuthenticated(): boolean
+  getToken(): string | null
+  getUser(): TUser | null
+  readonly user: TUser | null
+}
+
+/**
+ * Base class for session authentication
+ */
+export class SessionAuthAdapter<TUser extends AuthUser = AuthUser> implements ISessionAuthAdapter<TUser> {
+  /**
+   * Internal session state
+   * @protected
+   */
+  protected _token: string | null = null
+  protected _user: TUser | null = null
+
+  /**
+   * Authenticate user with credentials
+   *
+   * @param credentials - Login credentials
+   * @returns Session data
+   * @throws Error If authentication fails
+   *
+   * @example
+   * const { token, user } = await adapter.login({ username: 'admin', password: 'secret' })
+   */
+  async login(_credentials: LoginCredentials): Promise<SessionData<TUser>> {
+    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(): void {
+    throw new Error('[SessionAuthAdapter] logout() must be implemented by subclass')
+  }
+
+  /**
+   * Check if user is currently authenticated
+   *
+   * @returns True if user has valid session
+   *
+   * @example
+   * if (adapter.isAuthenticated()) {
+   *   // Show dashboard
+   * } else {
+   *   // Redirect to login
+   * }
+   */
+  isAuthenticated(): boolean {
+    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 JWT token or null if not authenticated
+   *
+   * @example
+   * const token = adapter.getToken()
+   * fetch('/api/data', {
+   *   headers: { Authorization: `Bearer ${token}` }
+   * })
+   */
+  getToken(): string | null {
+    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 User object or null if not authenticated
+   *
+   * @example
+   * const user = adapter.getUser()
+   * console.log(user.username, user.email, user.roles)
+   */
+  getUser(): TUser | null {
+    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.
+   */
+  get user(): TUser | null {
+    return this.getUser()
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Helper methods for subclasses
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Set session data (helper for subclasses)
+   *
+   * @param token - Authentication token
+   * @param user - User object
+   * @protected
+   */
+  protected setSession(token: string, user: TUser): void {
+    this._token = token
+    this._user = user
+  }
+
+  /**
+   * Clear session data (helper for subclasses)
+   *
+   * @protected
+   */
+  protected clearSession(): void {
+    this._token = null
+    this._user = null
+  }
+
+  /**
+   * Destroy session (catastrophic/silent logout)
+   *
+   * Clears token WITHOUT triggering normal logout signals.
+   * Used by DebugBar to test how the app handles unexpected session loss.
+   */
+  destroySession(): void {
+    this._token = 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: ISessionAuthAdapter): void {
+    const required: (keyof ISessionAuthAdapter)[] = ['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.'
+      )
+    }
+  }
+}
+
+/**
+ * Stored session data structure
+ */
+interface StoredSessionData<TUser = AuthUser> {
+  token: string
+  user: TUser
+  originalUser?: TUser
+}
+
+/**
+ * Configuration options for LocalStorageSessionAuthAdapter
+ */
+export interface LocalStorageAuthConfig {
+  /** localStorage key for session data (default: 'qdadm_auth') */
+  storageKey?: string
+}
+
+/**
+ * LocalStorage-based SessionAuthAdapter implementation
+ *
+ * Ready-to-use adapter that stores session in localStorage.
+ * Extend and override login() to add your API call.
+ *
+ * @example
+ * ```ts
+ * class MyAuthAdapter extends LocalStorageSessionAuthAdapter {
+ *   constructor() {
+ *     super('my_app_auth') // localStorage key
+ *   }
+ *
+ *   async login({ username, password }: LoginCredentials) {
+ *     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<TUser extends AuthUser = AuthUser> extends SessionAuthAdapter<TUser> {
+  /**
+   * Default configuration. Override to change defaults globally:
+   * @example
+   * LocalStorageSessionAuthAdapter.defaults.storageKey = 'my_app_auth'
+   */
+  static defaults: Required<LocalStorageAuthConfig> = {
+    storageKey: 'qdadm_auth'
+  }
+
+  protected _storageKey: string
+  protected _originalUser: TUser | null = null  // Stores original user during impersonation
+
+  /**
+   * @param config - Configuration options or storage key string (for backward compatibility)
+   */
+  constructor(config?: LocalStorageAuthConfig | string) {
+    super()
+    // Support both string (legacy) and config object
+    if (typeof config === 'string') {
+      this._storageKey = config
+    } else {
+      this._storageKey = config?.storageKey ?? LocalStorageSessionAuthAdapter.defaults.storageKey
+    }
+    this._restore()
+  }
+
+  /**
+   * Restore session from localStorage on init
+   * @private
+   */
+  private _restore(): void {
+    try {
+      const stored = localStorage.getItem(this._storageKey)
+      if (stored) {
+        const { token, user, originalUser } = JSON.parse(stored) as StoredSessionData<TUser>
+        this._token = token
+        this._user = user
+        this._originalUser = originalUser ?? null
+      }
+    } catch {
+      // Invalid stored data, ignore
+    }
+  }
+
+  /**
+   * Persist session to localStorage
+   * Call after login() to save session
+   * @protected
+   */
+  protected persist(): void {
+    if (this._token && this._user) {
+      const data: StoredSessionData<TUser> = {
+        token: this._token,
+        user: this._user
+      }
+      if (this._originalUser) {
+        data.originalUser = this._originalUser
+      }
+      localStorage.setItem(this._storageKey, JSON.stringify(data))
+    } else {
+      localStorage.removeItem(this._storageKey)
+    }
+  }
+
+  // Arrow functions to preserve `this` when used as callbacks
+  logout = (): void => {
+    this._originalUser = null
+    this.clearSession()
+    localStorage.removeItem(this._storageKey)
+  }
+
+  isAuthenticated = (): boolean => {
+    return !!this._token
+  }
+
+  getToken = (): string | null => {
+    return this._token
+  }
+
+  getUser = (): TUser | null => {
+    return this._user
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Impersonation support
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Check if currently impersonating another user
+   */
+  isImpersonating = (): boolean => {
+    return this._originalUser !== null
+  }
+
+  /**
+   * Get the original user (admin) when impersonating
+   * @returns Original user or null if not impersonating
+   */
+  getOriginalUser = (): TUser | null => {
+    return this._originalUser
+  }
+
+  /**
+   * Start impersonating another user
+   *
+   * @param targetUser - User to impersonate
+   * @returns The impersonated user
+   */
+  impersonate = (targetUser: TUser): TUser => {
+    if (!this._user) {
+      throw new Error('Must be authenticated to impersonate')
+    }
+    if (this._originalUser) {
+      throw new Error('Already impersonating. Stop first.')
+    }
+
+    this._originalUser = this._user
+    this._user = targetUser
+    this.persist()
+
+    return targetUser
+  }
+
+  /**
+   * Stop impersonating and return to original user
+   *
+   * @returns The original user
+   */
+  stopImpersonating = (): TUser => {
+    if (!this._originalUser) {
+      throw new Error('Not currently impersonating')
+    }
+
+    const original = this._originalUser
+    this._user = this._originalUser
+    this._originalUser = null
+    this.persist()
+
+    return original
+  }
+
+  /**
+   * Destroy session - clears token and localStorage
+   * @override
+   */
+  destroySession = (): void => {
+    this._token = null
+    localStorage.removeItem(this._storageKey)
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Signal integration
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Connect authAdapter to signals for reactive impersonation
+   *
+   * Call this during kernel boot to enable signal-driven impersonation.
+   * The adapter will listen to auth:impersonate and auth:impersonate:stop
+   * signals and update its internal state automatically.
+   *
+   * @param signals - Signals instance (from orchestrator.signals)
+   * @returns Cleanup function to unsubscribe
+   */
+  connectSignals(signals: SignalBus | null): () => void {
+    if (!signals) return () => {}
+
+    const cleanups: Array<() => void> = []
+
+    // Listen for impersonate signal
+    cleanups.push(signals.on('auth:impersonate', (event) => {
+      const data = event.data as { target?: TUser } | undefined
+      const targetUser = data?.target
+      if (targetUser && !this._originalUser) {
+        this._originalUser = this._user
+        this._user = targetUser
+        this.persist()
+      }
+    }))
+
+    // Listen for stop impersonation signal
+    cleanups.push(signals.on('auth:impersonate:stop', () => {
+      if (this._originalUser) {
+        this._user = this._originalUser
+        this._originalUser = null
+        this.persist()
+      }
+    }))
+
+    // Return cleanup function
+    return () => {
+      cleanups.forEach(cleanup => cleanup?.())
+    }
+  }
+}
+
+export default SessionAuthAdapter