qdadm 0.15.1 → 0.17.0

package/src/core/index.js

@@ -0,0 +1,28 @@
+/**
+ * Core Module
+ *
+ * Extension and helper utilities for qdadm modules.
+ */
+
+export {
+  extendModule,
+  ExtensionBuilder,
+} from './extension.js'
+
+export {
+  createDecoratedManager,
+  withAuditLog as withAuditLogDecorator,
+  withSoftDelete as withSoftDeleteDecorator,
+  withTimestamps as withTimestampsDecorator,
+  withValidation,
+} from './decorator.js'
+
+export {
+  createHookBundle,
+  applyBundle,
+  applyBundles,
+  withSoftDelete,
+  withTimestamps,
+  withVersioning,
+  withAuditLog,
+} from './bundles.js'

package/src/entity/EntityManager.js

@@ -1,3 +1,6 @@
+import { PermissiveAuthAdapter } from './auth/PermissiveAdapter.js'
+import { AuthActions } from './auth/AuthAdapter.js'
+
 /**
  * EntityManager - Base class for entity CRUD operations
  *
@@ -59,7 +62,9 @@ export class EntityManager {
       // Relations
       children = {},      // { roles: { entity: 'roles', endpoint?: ':id/roles' } }
       parent = null,      // { entity: 'users', foreignKey: 'user_id' }
-      relations = {}      // { groups: { entity: 'groups', through: 'user_groups' } }
+      relations = {},     // { groups: { entity: 'groups', through: 'user_groups' } }
+      // Auth adapter (for permission checks)
+      authAdapter = null  // AuthAdapter instance or null (uses PermissiveAuthAdapter)
     } = options
 
     this.name = name
@@ -86,6 +91,12 @@ export class EntityManager {
     this._relations = relations
     this._orchestrator = null  // Set when registered
 
+    // Auth adapter (fallback to permissive if not provided)
+    this._authAdapter = authAdapter
+
+    // HookRegistry reference for lifecycle hooks (set by Orchestrator)
+    this._hooks = null
+
     // Severity maps for status fields (field → value → severity)
     this._severityMaps = {}
 
@@ -97,6 +108,153 @@ export class EntityManager {
       valid: false     // Is cache currently valid?
     }
     this._cacheLoading = null  // Promise when cache is being loaded
+
+    // SignalBus reference for event emission (set by Orchestrator)
+    this._signals = null
+  }
+
+  // ============ SIGNALS ============
+
+  /**
+   * Set the SignalBus reference (called by Orchestrator during registration)
+   * @param {SignalBus} signals
+   */
+  setSignals(signals) {
+    this._signals = signals
+  }
+
+  /**
+   * Set the HookRegistry reference (called by Orchestrator during registration)
+   * @param {HookRegistry} hooks
+   */
+  setHooks(hooks) {
+    this._hooks = hooks
+  }
+
+  /**
+   * Get the HookRegistry reference
+   * @returns {HookRegistry|null}
+   */
+  get hooks() {
+    return this._hooks
+  }
+
+  /**
+   * Emit entity signals after CRUD operations
+   * Emits both entity-specific and generic signals via SignalBus.emitEntity
+   * @param {string} action - 'created', 'updated', or 'deleted'
+   * @param {object} data - Signal payload data { entity, id, ... }
+   * @private
+   */
+  _emitSignal(action, data) {
+    if (!this._signals) return
+    // Use SignalBus.emitEntity for proper dual-signal emission
+    this._signals.emitEntity(this.name, action, data)
+  }
+
+  // ============ LIFECYCLE HOOKS ============
+
+  /**
+   * Invoke a lifecycle hook for this entity
+   *
+   * Invokes both entity-specific hook (e.g., 'books:presave') and
+   * generic hook (e.g., 'entity:presave'). Entity-specific hooks run first.
+   *
+   * @param {string} hookName - Hook name without entity prefix (e.g., 'presave')
+   * @param {object} context - Hook context passed to handlers
+   * @private
+   */
+  async _invokeHook(hookName, context) {
+    if (!this._hooks) return
+
+    // Invoke entity-specific hook first (e.g., 'books:presave')
+    await this._hooks.invoke(`${this.name}:${hookName}`, context)
+
+    // Invoke generic hook (e.g., 'entity:presave')
+    await this._hooks.invoke(`entity:${hookName}`, context)
+  }
+
+  /**
+   * Build hook context for presave operations
+   *
+   * @typedef {object} PresaveContext
+   * @property {string} entity - Entity name
+   * @property {object} record - Record data (can be mutated by handlers)
+   * @property {boolean} isNew - True for create, false for update
+   * @property {string|number} [id] - Record ID (only for update)
+   * @property {EntityManager} manager - This manager instance
+   *
+   * @param {object} data - Record data
+   * @param {boolean} isNew - True for create, false for update
+   * @param {string|number} [id] - Record ID (only for update)
+   * @returns {PresaveContext}
+   * @private
+   */
+  _buildPresaveContext(data, isNew, id = null) {
+    const context = {
+      entity: this.name,
+      record: data,
+      isNew,
+      manager: this
+    }
+    if (!isNew && id !== null) {
+      context.id = id
+    }
+    return context
+  }
+
+  /**
+   * Build hook context for postsave operations
+   *
+   * @typedef {object} PostsaveContext
+   * @property {string} entity - Entity name
+   * @property {object} record - Original record data
+   * @property {object} result - Saved entity returned from storage
+   * @property {boolean} isNew - True for create, false for update
+   * @property {string|number} [id] - Record ID
+   * @property {EntityManager} manager - This manager instance
+   *
+   * @param {object} data - Original record data
+   * @param {object} result - Saved entity from storage
+   * @param {boolean} isNew - True for create, false for update
+   * @param {string|number} [id] - Record ID
+   * @returns {PostsaveContext}
+   * @private
+   */
+  _buildPostsaveContext(data, result, isNew, id = null) {
+    const context = {
+      entity: this.name,
+      record: data,
+      result,
+      isNew,
+      manager: this
+    }
+    if (id !== null) {
+      context.id = id
+    } else if (result?.[this.idField]) {
+      context.id = result[this.idField]
+    }
+    return context
+  }
+
+  /**
+   * Build hook context for predelete operations
+   *
+   * @typedef {object} PredeleteContext
+   * @property {string} entity - Entity name
+   * @property {string|number} id - Record ID to be deleted
+   * @property {EntityManager} manager - This manager instance
+   *
+   * @param {string|number} id - Record ID to delete
+   * @returns {PredeleteContext}
+   * @private
+   */
+  _buildPredeleteContext(id) {
+    return {
+      entity: this.name,
+      id,
+      manager: this
+    }
   }
 
   // ============ METADATA ACCESSORS ============
@@ -159,9 +317,71 @@ export class EntityManager {
 
   // ============ PERMISSIONS ============
 
+  /**
+   * Get the auth adapter (lazy-initialized PermissiveAuthAdapter if not set)
+   * @returns {AuthAdapter}
+   */
+  get authAdapter() {
+    if (!this._authAdapter) {
+      this._authAdapter = new PermissiveAuthAdapter()
+    }
+    return this._authAdapter
+  }
+
+  /**
+   * Set the auth adapter
+   * @param {AuthAdapter|null} adapter
+   */
+  set authAdapter(adapter) {
+    this._authAdapter = adapter
+  }
+
+  /**
+   * Check if the current user can perform an action, optionally on a specific record
+   *
+   * This is the primary permission check method. It combines:
+   * 1. Local restrictions (readOnly, scopeWhitelist)
+   * 2. Scope check via AuthAdapter.canPerform() - can user do this action type?
+   * 3. Silo check via AuthAdapter.canAccessRecord() - can user access this record?
+   *
+   * @param {string} action - Action to check: 'read', 'create', 'update', 'delete', 'list'
+   * @param {object} [record] - Optional: specific record to check (for silo validation)
+   * @returns {boolean} - true if action is allowed
+   *
+   * @example
+   * // Scope-only checks (no record)
+   * manager.canAccess('create')       // Can user create new items?
+   * manager.canAccess('list')         // Can user see the list?
+   *
+   * @example
+   * // Scope + silo checks (with record)
+   * manager.canAccess('read', item)   // Can user see this specific item?
+   * manager.canAccess('update', item) // Can user edit this specific item?
+   * manager.canAccess('delete', item) // Can user delete this specific item?
+   */
+  canAccess(action, record = null) {
+    // 1. Check readOnly restriction for write actions
+    if (this._readOnly && action !== AuthActions.READ && action !== AuthActions.LIST) {
+      return false
+    }
+
+    // 2. Scope check: can user perform this action on this entity type?
+    const canPerformAction = this.authAdapter.canPerform(this.name, action)
+    if (!canPerformAction) {
+      return false
+    }
+
+    // 3. Silo check: if record provided, can user access this specific record?
+    if (record !== null) {
+      return this.authAdapter.canAccessRecord(this.name, record)
+    }
+
+    return true
+  }
+
   /**
    * Check if user can read entities
-   * Override in subclass or provide via options to implement custom logic
+   * Delegates to canAccess('read', entity)
    *
    * @param {object} [entity] - Optional: specific entity to check
    * @returns {boolean} - true if user can read
@@ -170,8 +390,7 @@ export class EntityManager {
    * With entity: specific read permission (e.g., can see this item)
    */
   canRead(entity = null) {
-    // Default: allow all reads
-    return true
+    return this.canAccess(AuthActions.READ, entity)
   }
 
   /**
@@ -184,18 +403,17 @@ export class EntityManager {
 
   /**
    * Check if user can create new entities
-   * Override in subclass to implement custom logic
+   * Delegates to canAccess('create')
    *
    * @returns {boolean} - true if user can create
    */
   canCreate() {
-    if (this._readOnly) return false
-    return true
+    return this.canAccess(AuthActions.CREATE)
   }
 
   /**
    * Check if user can update entities
-   * Override in subclass to implement custom logic
+   * Delegates to canAccess('update', entity)
    *
    * @param {object} [entity] - Optional: specific entity to check
    * @returns {boolean} - true if user can update
@@ -204,20 +422,28 @@ export class EntityManager {
    * With entity: specific update permission (e.g., can edit this item)
    */
   canUpdate(entity = null) {
-    if (this._readOnly) return false
-    return true
+    return this.canAccess(AuthActions.UPDATE, entity)
   }
 
   /**
    * Check if user can delete entities
-   * Override in subclass or provide via options to implement custom logic
+   * Delegates to canAccess('delete', entity)
    *
    * @param {object} [entity] - Optional: specific entity to check
    * @returns {boolean} - true if user can delete
    */
   canDelete(entity = null) {
-    if (this._readOnly) return false
-    return true
+    return this.canAccess(AuthActions.DELETE, entity)
+  }
+
+  /**
+   * Check if user can list entities
+   * Delegates to canAccess('list')
+   *
+   * @returns {boolean} - true if user can list
+   */
+  canList() {
+    return this.canAccess(AuthActions.LIST)
   }
 
   /**
@@ -465,13 +691,33 @@ export class EntityManager {
 
   /**
    * Create a new entity
+   *
+   * Lifecycle hooks invoked:
+   * - presave: Before storage.create(), can modify data or throw to abort
+   * - postsave: After successful storage.create(), for side effects
+   *
    * @param {object} data
    * @returns {Promise<object>} - The created entity
    */
   async create(data) {
     if (this.storage) {
-      const result = await this.storage.create(data)
+      // Invoke presave hooks (can modify data or throw to abort)
+      const presaveContext = this._buildPresaveContext(data, true)
+      await this._invokeHook('presave', presaveContext)
+
+      // Use potentially modified data from context
+      const result = await this.storage.create(presaveContext.record)
       this.invalidateCache()
+
+      // Invoke postsave hooks (for side effects)
+      const postsaveContext = this._buildPostsaveContext(data, result, true)
+      await this._invokeHook('postsave', postsaveContext)
+
+      this._emitSignal('created', {
+        entity: result,
+        manager: this.name,
+        id: result?.[this.idField]
+      })
       return result
     }
     throw new Error(`[EntityManager:${this.name}] create() not implemented`)
@@ -479,14 +725,34 @@ export class EntityManager {
 
   /**
    * Update an entity (PUT - full replacement)
+   *
+   * Lifecycle hooks invoked:
+   * - presave: Before storage.update(), can modify data or throw to abort
+   * - postsave: After successful storage.update(), for side effects
+   *
    * @param {string|number} id
    * @param {object} data
    * @returns {Promise<object>}
    */
   async update(id, data) {
     if (this.storage) {
-      const result = await this.storage.update(id, data)
+      // Invoke presave hooks (can modify data or throw to abort)
+      const presaveContext = this._buildPresaveContext(data, false, id)
+      await this._invokeHook('presave', presaveContext)
+
+      // Use potentially modified data from context
+      const result = await this.storage.update(id, presaveContext.record)
       this.invalidateCache()
+
+      // Invoke postsave hooks (for side effects)
+      const postsaveContext = this._buildPostsaveContext(data, result, false, id)
+      await this._invokeHook('postsave', postsaveContext)
+
+      this._emitSignal('updated', {
+        entity: result,
+        manager: this.name,
+        id
+      })
       return result
     }
     throw new Error(`[EntityManager:${this.name}] update() not implemented`)
@@ -494,14 +760,34 @@ export class EntityManager {
 
   /**
    * Partially update an entity (PATCH)
+   *
+   * Lifecycle hooks invoked:
+   * - presave: Before storage.patch(), can modify data or throw to abort
+   * - postsave: After successful storage.patch(), for side effects
+   *
    * @param {string|number} id
    * @param {object} data
    * @returns {Promise<object>}
    */
   async patch(id, data) {
     if (this.storage) {
-      const result = await this.storage.patch(id, data)
+      // Invoke presave hooks (can modify data or throw to abort)
+      const presaveContext = this._buildPresaveContext(data, false, id)
+      await this._invokeHook('presave', presaveContext)
+
+      // Use potentially modified data from context
+      const result = await this.storage.patch(id, presaveContext.record)
       this.invalidateCache()
+
+      // Invoke postsave hooks (for side effects)
+      const postsaveContext = this._buildPostsaveContext(data, result, false, id)
+      await this._invokeHook('postsave', postsaveContext)
+
+      this._emitSignal('updated', {
+        entity: result,
+        manager: this.name,
+        id
+      })
       return result
     }
     throw new Error(`[EntityManager:${this.name}] patch() not implemented`)
@@ -509,13 +795,25 @@ export class EntityManager {
 
   /**
    * Delete an entity
+   *
+   * Lifecycle hooks invoked:
+   * - predelete: Before storage.delete(), can throw to abort (for cascade checks)
+   *
    * @param {string|number} id
    * @returns {Promise<void>}
    */
   async delete(id) {
     if (this.storage) {
+      // Invoke predelete hooks (can throw to abort, e.g., for cascade checks)
+      const predeleteContext = this._buildPredeleteContext(id)
+      await this._invokeHook('predelete', predeleteContext)
+
       const result = await this.storage.delete(id)
       this.invalidateCache()
+      this._emitSignal('deleted', {
+        manager: this.name,
+        id
+      })
       return result
     }
     throw new Error(`[EntityManager:${this.name}] delete() not implemented`)

package/src/entity/auth/AuthAdapter.js

@@ -0,0 +1,125 @@
+/**
+ * AuthAdapter - Interface for scope and silo permission checks
+ *
+ * Applications implement this interface to plug their authentication/authorization
+ * system into qdadm's EntityManager. The adapter provides two levels of permission checks:
+ *
+ * 1. **Scopes** (action-level): Can the user perform this action on this entity type?
+ *    Example: Can user create invoices? Can user delete users?
+ *
+ * 2. **Silos** (record-level): Can the user access this specific record?
+ *    Example: Can user see invoice #123? (ownership, team membership, etc.)
+ *
+ * Usage:
+ * ```js
+ * class MyAuthAdapter extends AuthAdapter {
+ *   canPerform(entity, action) {
+ *     const user = this.getCurrentUser()
+ *     return user?.permissions?.includes(`${entity}:${action}`)
+ *   }
+ *
+ *   canAccessRecord(entity, record) {
+ *     const user = this.getCurrentUser()
+ *     // Check ownership or team membership
+ *     return record.owner_id === user?.id || record.team_id === user?.team_id
+ *   }
+ *
+ *   getCurrentUser() {
+ *     return this._userStore.currentUser
+ *   }
+ * }
+ * ```
+ *
+ * @interface
+ */
+export class AuthAdapter {
+  /**
+   * Check if the current user can perform an action on an entity type (scope check)
+   *
+   * This is the coarse-grained permission check. It determines if the user has
+   * the right to perform a category of actions, regardless of which specific
+   * record they want to act on.
+   *
+   * @param {string} entity - Entity name (e.g., 'users', 'invoices', 'products')
+   * @param {string} action - Action to check: 'read', 'create', 'update', 'delete', 'list'
+   * @returns {boolean} True if user can perform the action on this entity type
+   *
+   * @example
+   * // Check if user can create invoices
+   * adapter.canPerform('invoices', 'create') // true/false
+   *
+   * // Check if user can delete users
+   * adapter.canPerform('users', 'delete') // true/false
+   */
+  canPerform(entity, action) {
+    throw new Error('[AuthAdapter] canPerform() must be implemented by subclass')
+  }
+
+  /**
+   * Check if the current user can access a specific record (silo check)
+   *
+   * This is the fine-grained permission check. After the scope check passes,
+   * this determines if the user can access a particular record based on
+   * ownership, team membership, or other business rules.
+   *
+   * Called during:
+   * - get() operations
+   * - update() / patch() operations
+   * - delete() operations
+   * - list() result filtering (optional)
+   *
+   * @param {string} entity - Entity name (e.g., 'users', 'invoices')
+   * @param {object} record - The full entity record to check access for
+   * @returns {boolean} True if user can access this specific record
+   *
+   * @example
+   * // Check if user can access a specific invoice
+   * adapter.canAccessRecord('invoices', { id: 123, owner_id: 456, ... })
+   *
+   * @example
+   * // Common implementations:
+   * // 1. Ownership: record.owner_id === user.id
+   * // 2. Team: record.team_id === user.team_id
+   * // 3. Role: user.role === 'admin' (admins see all)
+   * // 4. Hierarchical: record.organization_id in user.organizations
+   */
+  canAccessRecord(entity, record) {
+    throw new Error('[AuthAdapter] canAccessRecord() must be implemented by subclass')
+  }
+
+  /**
+   * Get the current authenticated user
+   *
+   * Returns the user object or null if not authenticated. The user object
+   * should contain whatever information is needed for permission checks
+   * (id, role, team_id, permissions array, etc.).
+   *
+   * @returns {object|null} Current user object or null if not authenticated
+   *
+   * @example
+   * // Typical user object:
+   * {
+   *   id: 123,
+   *   email: 'user@example.com',
+   *   role: 'manager',
+   *   team_id: 456,
+   *   permissions: ['invoices:create', 'invoices:read', 'users:read']
+   * }
+   */
+  getCurrentUser() {
+    throw new Error('[AuthAdapter] getCurrentUser() must be implemented by subclass')
+  }
+}
+
+/**
+ * Valid action types for scope checks
+ * @readonly
+ * @enum {string}
+ */
+export const AuthActions = Object.freeze({
+  READ: 'read',
+  CREATE: 'create',
+  UPDATE: 'update',
+  DELETE: 'delete',
+  LIST: 'list'
+})

package/src/entity/auth/PermissiveAdapter.js

@@ -0,0 +1,64 @@
+/**
+ * PermissiveAuthAdapter - Default adapter that allows all operations
+ *
+ * This adapter is used when no custom AuthAdapter is provided to EntityManager.
+ * It returns `true` for all permission checks, effectively disabling authorization.
+ *
+ * Use cases:
+ * - Development/prototyping without auth setup
+ * - Backward compatibility with existing apps that don't use auth
+ * - Internal admin tools with implicit trust
+ * - Testing environments
+ *
+ * @example
+ * // Explicit usage (rarely needed)
+ * const adapter = new PermissiveAuthAdapter()
+ *
+ * adapter.canPerform('users', 'delete') // true
+ * adapter.canAccessRecord('invoices', { id: 123, secret: true }) // true
+ * adapter.getCurrentUser() // null
+ *
+ * @extends AuthAdapter
+ */
+import { AuthAdapter } from './AuthAdapter.js'
+
+export class PermissiveAuthAdapter extends AuthAdapter {
+  /**
+   * Always allows any action on any entity type
+   *
+   * @param {string} entity - Entity name (ignored)
+   * @param {string} action - Action to check (ignored)
+   * @returns {boolean} Always returns true
+   */
+  canPerform(entity, action) {
+    return true
+  }
+
+  /**
+   * Always allows access to any record
+   *
+   * @param {string} entity - Entity name (ignored)
+   * @param {object} record - The record (ignored)
+   * @returns {boolean} Always returns true
+   */
+  canAccessRecord(entity, record) {
+    return true
+  }
+
+  /**
+   * Returns null (no authenticated user in permissive mode)
+   *
+   * @returns {null} Always returns null
+   */
+  getCurrentUser() {
+    return null
+  }
+}
+
+/**
+ * Factory function to create a PermissiveAuthAdapter
+ * @returns {PermissiveAuthAdapter}
+ */
+export function createPermissiveAdapter() {
+  return new PermissiveAuthAdapter()
+}

package/src/entity/auth/index.js

@@ -0,0 +1,11 @@
+/**
+ * Auth Module
+ *
+ * AuthAdapter interface and implementations for scope/silo permission checks.
+ */
+
+// Interface
+export { AuthAdapter, AuthActions } from './AuthAdapter.js'
+
+// Implementations
+export { PermissiveAuthAdapter, createPermissiveAdapter } from './PermissiveAdapter.js'

package/src/entity/index.js

@@ -9,3 +9,6 @@ export { EntityManager, createEntityManager } from './EntityManager.js'
 
 // Storage adapters
 export * from './storage/index.js'
+
+// Auth adapters
+export * from './auth/index.js'