@quazardous/qdadm 1.19.3

package/src/entity/EntityManager.types.ts

@@ -0,0 +1,288 @@
+import type {
+  EntityRecord,
+  ListResult,
+  IStorage,
+  FieldConfig,
+  ChildConfig,
+  ParentConfig,
+  RelationConfig,
+  NavConfig,
+  StorageCapabilities,
+} from '../types'
+import type { AuthUser, EntityAuthAdapter as IEntityAuthAdapter } from './auth/EntityAuthAdapter'
+import type { SignalBus } from '../kernel/SignalBus'
+import type { HookRegistry } from '../hooks/HookRegistry'
+
+// Circular type import — safe because `import type` is erased at runtime
+import type { EntityManager } from './EntityManager'
+
+// ============ INTERNAL TYPES ============
+
+/**
+ * Cache state for local filtering
+ */
+export interface CacheState<T> {
+  items: T[]
+  total: number
+  loadedAt: number | null
+  valid: boolean
+}
+
+/**
+ * Detail cache entry for asymmetric entities (full detail per item)
+ */
+export interface DetailCacheEntry<T> {
+  item: T
+  loadedAt: number
+}
+
+/**
+ * Detail cache state for asymmetric entities
+ */
+export interface DetailCacheState<T> {
+  items: Map<string, DetailCacheEntry<T>>
+}
+
+/**
+ * Operation stats for debugging
+ */
+export interface OperationStats {
+  list: number
+  get: number
+  create: number
+  update: number
+  delete: number
+  cacheHits: number
+  cacheMisses: number
+  detailCacheHits: number
+  detailCacheMisses: number
+  maxItemsSeen: number
+  maxTotal: number
+}
+
+/**
+ * Resolved storage result
+ */
+export interface ResolvedStorage<T extends EntityRecord> {
+  storage: IStorage<T> | null | undefined
+  endpoint?: string
+  params?: Record<string, unknown>
+  isDynamic?: boolean
+}
+
+/**
+ * Storage resolution result (what resolveStorage returns)
+ */
+export type StorageResolution<T extends EntityRecord> =
+  | string
+  | ((context: RoutingContext | undefined) => string)
+  | {
+      storage?: IStorage<T> | null
+      endpoint?: string | ((context: RoutingContext | undefined) => string)
+      params?: Record<string, unknown>
+    }
+  | null
+  | undefined
+
+/**
+ * Routing context for multi-storage patterns
+ */
+export interface RoutingContext {
+  parentChain?: Array<{ entity: string; id: string | number }>
+  [key: string]: unknown
+}
+
+/**
+ * Presave hook context
+ */
+export interface PresaveContext<T extends EntityRecord = EntityRecord> {
+  entity: string
+  record: Partial<T>
+  isNew: boolean
+  id?: string | number
+  manager: EntityManager<T>
+}
+
+/**
+ * Postsave hook context
+ */
+export interface PostsaveContext<T extends EntityRecord = EntityRecord> {
+  entity: string
+  record: Partial<T>
+  result: T
+  isNew: boolean
+  id?: string | number
+  manager: EntityManager<T>
+}
+
+/**
+ * Predelete hook context
+ */
+export interface PredeleteContext<T extends EntityRecord = EntityRecord> {
+  entity: string
+  id: string | number
+  manager: EntityManager<T>
+}
+
+/**
+ * Query options
+ */
+export interface QueryOptions {
+  context?: WhitelistContext
+  routingContext?: RoutingContext | null
+}
+
+/**
+ * Whitelist check context
+ */
+export interface WhitelistContext {
+  module?: string
+  scope?: string
+  form?: string
+  field?: string
+  bypassPermissions?: boolean
+  reason?: string
+}
+
+/**
+ * Cache info for debugging
+ */
+export interface CacheInfo {
+  enabled: boolean
+  storageSupportsTotal: boolean
+  threshold: number
+  valid: boolean
+  overflow: boolean
+  itemCount: number
+  total: number
+  loadedAt: number | null
+  /** Effective TTL in milliseconds (0 = no TTL) */
+  ttlMs: number
+  /** Timestamp when cache expires (null if no TTL) */
+  expiresAt: number | null
+  /** Whether the cache has expired based on TTL */
+  expired: boolean
+  /** Whether the entity uses asymmetric mode (list vs detail separation) */
+  asymmetric: boolean
+  /** Detail cache info (only populated when asymmetric + detail cache enabled) */
+  detailCache: {
+    enabled: boolean
+    ttlMs: number
+    size: number
+    maxSize: number
+  } | null
+}
+
+/**
+ * Badge descriptor for entity item headers
+ */
+export interface EntityBadge {
+  label: string
+  severity?: 'secondary' | 'info' | 'success' | 'warn' | 'danger' | 'contrast'
+}
+
+/**
+ * Rich severity descriptor for a field value.
+ * Extends beyond a simple severity string to support icons and label overrides.
+ */
+export interface SeverityDescriptor {
+  severity: string
+  icon?: string
+  label?: string
+}
+
+/** A severity map value: plain string (backward compat) or rich descriptor */
+export type SeverityMapValue = string | SeverityDescriptor
+
+/** Severity map: field value → severity string or descriptor */
+export type SeverityMap = Record<string, SeverityMapValue>
+
+/**
+ * EntityManager constructor options
+ */
+export interface EntityManagerOptions<T extends EntityRecord = EntityRecord> {
+  name: string
+  storage?: IStorage<T> | null
+  idField?: string
+  label?: string
+  labelPlural?: string
+  routePrefix?: string
+  labelField?: string | ((entity: T) => string)
+  /** Callback to compute badges for an entity item header */
+  badges?: (entity: T) => EntityBadge[]
+  fields?: Record<string, FieldConfig>
+  localFilterThreshold?: number | null
+  /** Cache TTL in milliseconds (0=disabled, -1=infinite, >0=TTL). Overrides global, overridden by storage. */
+  cacheTtlMs?: number | null
+  /** Asymmetric mode: list() and get() return different structures. get() skips list cache. */
+  asymmetric?: boolean
+  /** Detail cache TTL in milliseconds (0=disabled (default), -1=infinite, >0=TTL). Only used when asymmetric=true. */
+  detailCacheTtlMs?: number
+  /** Detail cache max size (0=unlimited (default), >0=max items). Oldest entries are evicted when exceeded. Only used when asymmetric=true. */
+  detailCacheMaxSize?: number
+  readOnly?: boolean
+  warmup?: boolean
+  authSensitive?: boolean
+  system?: boolean
+  scopeWhitelist?: string[] | null
+  isOwn?: ((record: T, user: AuthUser) => boolean) | null
+  children?: Record<string, ChildConfig>
+  parent?: ParentConfig | null
+  parents?: Record<string, ParentConfig>
+  relations?: Record<string, RelationConfig>
+  authAdapter?: IEntityAuthAdapter | null
+  nav?: NavConfig
+}
+
+// Forward declaration for Orchestrator (to avoid circular deps)
+export interface Orchestrator {
+  get<T extends EntityRecord>(name: string): EntityManager<T> | undefined
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  kernel?: any
+  deferred?: DeferredRegistry | null
+}
+
+// Forward declaration for DeferredRegistry
+export interface DeferredRegistry {
+  has(key: string): boolean
+  await(key: string): Promise<unknown>
+  queue<T>(key: string, fn: () => Promise<T>): Promise<T>
+}
+
+/**
+ * Exposes protected members of EntityManager for use by prototype-patched helper methods.
+ * @internal
+ */
+export type EntityManagerInternal<T extends EntityRecord = EntityRecord> = EntityManager<T> & {
+  // Protected fields accessed by helpers
+  _cache: CacheState<T>
+  _cacheLoading: Promise<boolean> | null
+  _cacheTtlMs: number | null
+  _asymmetric: boolean
+  _detailCache: DetailCacheState<T>
+  _detailCacheTtlMs: number
+  _detailCacheMaxSize: number
+  _detailInflight: Map<string, Promise<T>>
+  _orchestrator: Orchestrator | null
+  _parents: Record<string, ParentConfig>
+  _parent: ParentConfig | null
+  _children: Record<string, ChildConfig>
+  _authSensitive: boolean
+  _signals: SignalBus | null
+  _signalCleanup: (() => void) | null
+  _warmup: boolean
+  _stats: OperationStats
+
+  // Protected methods that stay in the class body
+  _normalizeResolveResult(result: StorageResolution<T>, context?: RoutingContext): ResolvedStorage<T>
+  _buildPresaveContext(data: Partial<T>, isNew: boolean, id?: string | number | null): PresaveContext<T>
+  _buildPostsaveContext(data: Partial<T>, result: T, isNew: boolean, id?: string | number | null): PostsaveContext<T>
+  _buildPredeleteContext(id: string | number): PredeleteContext<T>
+  _emitSignal(action: 'created' | 'updated' | 'deleted', data: Record<string, unknown>): void
+  _emitDataInvalidate(action: 'created' | 'updated' | 'deleted', id: string | number | undefined): void
+  _invokeHook(hookName: string, context: Record<string, unknown>): Promise<void>
+}
+
+// Re-export types used by helpers
+export type { EntityRecord, ListResult, IStorage, StorageCapabilities }
+export type { SignalBus, HookRegistry }

package/src/entity/auth/CompositeAuthAdapter.ts

@@ -0,0 +1,194 @@
+/**
+ * CompositeAuthAdapter - Routes to sub-adapters based on entity patterns
+ *
+ * Enables multi-source authentication where different entities may use
+ * different auth backends (internal JWT, external API keys, OAuth, etc.)
+ *
+ * Pattern matching:
+ * - Exact match: 'products' matches only 'products'
+ * - Prefix glob: 'external-*' matches 'external-products', 'external-orders'
+ * - Suffix glob: '*-readonly' matches 'products-readonly'
+ */
+
+import { EntityAuthAdapter } from './EntityAuthAdapter'
+import { authFactory, type AuthFactoryContext } from './factory'
+
+/**
+ * Pattern match entry
+ */
+interface PatternEntry {
+  pattern: string
+  regex: RegExp
+  adapter: EntityAuthAdapter
+}
+
+/**
+ * Composite adapter config
+ */
+export interface CompositeAuthConfig {
+  default: EntityAuthAdapter | string | Record<string, unknown>
+  mapping?: Record<string, EntityAuthAdapter | string | Record<string, unknown>>
+}
+
+/**
+ * CompositeAuthAdapter - Routes to sub-adapters based on entity patterns
+ */
+export class CompositeAuthAdapter extends EntityAuthAdapter {
+  protected _default: EntityAuthAdapter
+  protected _exactMatches: Map<string, EntityAuthAdapter>
+  protected _patterns: PatternEntry[]
+
+  constructor(config: CompositeAuthConfig, context: AuthFactoryContext = {}) {
+    super()
+
+    const { default: defaultConfig, mapping = {} } = config
+
+    if (!defaultConfig) {
+      throw new Error('[CompositeAuthAdapter] "default" adapter is required')
+    }
+
+    // Resolve default adapter via factory
+    this._default = authFactory(defaultConfig, context)
+
+    // Resolve mapped adapters
+    this._exactMatches = new Map()
+    this._patterns = []
+
+    for (const [pattern, adapterConfig] of Object.entries(mapping)) {
+      const adapter = authFactory(adapterConfig, context)
+
+      if (pattern.includes('*')) {
+        // Glob pattern: convert to regex
+        const regexPattern = pattern
+          .replace(/[.+?^${}()|[\]\\]/g, '\\$&') // Escape regex special chars
+          .replace(/\*/g, '.*') // * → .*
+        const regex = new RegExp(`^${regexPattern}$`)
+        this._patterns.push({ pattern, regex, adapter })
+      } else {
+        // Exact match
+        this._exactMatches.set(pattern, adapter)
+      }
+    }
+  }
+
+  /**
+   * Get the adapter for a specific entity
+   */
+  protected _getAdapter(entity: string): EntityAuthAdapter {
+    // 1. Exact match
+    const exactMatch = this._exactMatches.get(entity)
+    if (exactMatch) {
+      return exactMatch
+    }
+
+    // 2. Pattern match (first wins)
+    for (const { regex, adapter } of this._patterns) {
+      if (regex.test(entity)) {
+        return adapter
+      }
+    }
+
+    // 3. Default
+    return this._default
+  }
+
+  /**
+   * Check if user can perform action on entity type (scope check)
+   */
+  canPerform(entity: string, action: string): boolean {
+    return this._getAdapter(entity).canPerform(entity, action)
+  }
+
+  /**
+   * Check if user can access specific record (silo check)
+   */
+  canAccessRecord(entity: string, record: unknown): boolean {
+    return this._getAdapter(entity).canAccessRecord(entity, record)
+  }
+
+  /**
+   * Get current user from the default adapter
+   */
+  getCurrentUser() {
+    return this._default.getCurrentUser()
+  }
+
+  /**
+   * Check if user is granted an attribute (role or permission)
+   */
+  isGranted(attribute: string, subject: unknown = null): boolean {
+    // For entity-specific permissions (entity:action), route to appropriate adapter
+    if (attribute.includes(':') && !attribute.startsWith('ROLE_')) {
+      const parts = attribute.split(':')
+      const entity = parts[0] || ''
+      const adapter = this._getAdapter(entity)
+      if ('isGranted' in adapter && typeof adapter.isGranted === 'function') {
+        return adapter.isGranted(attribute, subject)
+      }
+    }
+
+    // Global permissions use default adapter
+    if ('isGranted' in this._default && typeof this._default.isGranted === 'function') {
+      return this._default.isGranted(attribute, subject)
+    }
+
+    // Fallback for adapters without isGranted
+    return true
+  }
+
+  /**
+   * Get the default adapter
+   */
+  get defaultAdapter(): EntityAuthAdapter {
+    return this._default
+  }
+
+  /**
+   * Get adapter info for debugging
+   */
+  getAdapterInfo(): {
+    default: string
+    exactMatches: Record<string, string>
+    patterns: Array<{ pattern: string; adapter: string }>
+  } {
+    const info: {
+      default: string
+      exactMatches: Record<string, string>
+      patterns: Array<{ pattern: string; adapter: string }>
+    } = {
+      default: this._getAdapterName(this._default),
+      exactMatches: {},
+      patterns: [],
+    }
+
+    for (const [entity, adapter] of this._exactMatches) {
+      info.exactMatches[entity] = this._getAdapterName(adapter)
+    }
+
+    for (const { pattern, adapter } of this._patterns) {
+      info.patterns.push({
+        pattern,
+        adapter: this._getAdapterName(adapter),
+      })
+    }
+
+    return info
+  }
+
+  /**
+   * Get adapter name for debugging
+   */
+  protected _getAdapterName(adapter: EntityAuthAdapter): string {
+    return adapter.constructor?.name || 'Unknown'
+  }
+}
+
+/**
+ * Factory function to create CompositeAuthAdapter
+ */
+export function createCompositeAuthAdapter(
+  config: CompositeAuthConfig,
+  context: AuthFactoryContext = {}
+): CompositeAuthAdapter {
+  return new CompositeAuthAdapter(config, context)
+}

package/src/entity/auth/EntityAuthAdapter.ts

@@ -0,0 +1,119 @@
+import type { SecurityChecker } from './SecurityChecker'
+
+/**
+ * User type for auth checks
+ */
+export interface AuthUser {
+  id?: string | number
+  role?: string
+  roles?: string[]
+  permissions?: string[]
+  [key: string]: unknown
+}
+
+/**
+ * EntityAuthAdapter options
+ */
+export interface EntityAuthAdapterOptions {
+  getCurrentUser?: () => AuthUser | null
+}
+
+/**
+ * EntityAuthAdapter - Thin layer for entity-level permission checks
+ *
+ * Provides entity-level permission checking by delegating to SecurityChecker.
+ * All methods have sensible defaults - subclass only if you need custom behavior.
+ */
+export class EntityAuthAdapter {
+  protected _securityChecker: SecurityChecker | null = null
+  protected _getCurrentUserCallback: (() => AuthUser | null) | null = null
+
+  constructor(options: EntityAuthAdapterOptions = {}) {
+    if (options.getCurrentUser) {
+      this._getCurrentUserCallback = options.getCurrentUser
+    }
+  }
+
+  /**
+   * Set the SecurityChecker instance for isGranted() delegation
+   */
+  setSecurityChecker(checker: SecurityChecker): void {
+    this._securityChecker = checker
+  }
+
+  /**
+   * Check if current user is granted an attribute (Symfony-like contract)
+   *
+   * This is the unified permission check method. It delegates to SecurityChecker
+   * if one is configured, otherwise returns true (permissive fallback).
+   */
+  isGranted(attribute: string, subject: unknown = null): boolean {
+    if (!this._securityChecker) return true // Permissive if not configured
+    return this._securityChecker.isGranted(attribute, subject)
+  }
+
+  /**
+   * Check if current user can assign a specific role
+   */
+  canAssignRole(targetRole: string): boolean {
+    if (!this._securityChecker) return true
+    return this._securityChecker.canAssignRole(targetRole)
+  }
+
+  /**
+   * Get all roles that current user can assign
+   */
+  getAssignableRoles(): string[] {
+    if (!this._securityChecker) return []
+    return this._securityChecker.getAssignableRoles()
+  }
+
+  /**
+   * Check if the current user can perform an action on an entity type (scope check)
+   *
+   * Default: delegates to isGranted('entity:{entity}:{action}')
+   * Override for custom authentication requirements or business rules.
+   */
+  canPerform(_entity: string, _action: string): boolean {
+    return this.isGranted(`entity:${_entity}:${_action}`)
+  }
+
+  /**
+   * Check if the current user can access a specific record (silo check)
+   *
+   * Default: delegates to isGranted('entity:{entity}:read', record)
+   * Note: Ownership checks are typically handled via EntityManager's isOwn callback.
+   */
+  canAccessRecord(_entity: string, record: unknown): boolean {
+    return this.isGranted(`entity:${_entity}:read`, record)
+  }
+
+  /**
+   * Get the current authenticated user
+   *
+   * Returns user from:
+   * 1. _getCurrentUserCallback if provided in constructor
+   * 2. Subclass override if using class extension pattern
+   * 3. null if neither is configured
+   */
+  getCurrentUser(): AuthUser | null {
+    if (this._getCurrentUserCallback) {
+      return this._getCurrentUserCallback()
+    }
+    // Subclasses can override this method
+    return null
+  }
+}
+
+/**
+ * Valid action types for scope checks
+ */
+export const AuthActions = Object.freeze({
+  READ: 'read',
+  CREATE: 'create',
+  UPDATE: 'update',
+  DELETE: 'delete',
+  LIST: 'list',
+} as const)
+
+export type AuthAction = (typeof AuthActions)[keyof typeof AuthActions]

package/src/entity/auth/PermissiveAdapter.ts

@@ -0,0 +1,43 @@
+/**
+ * PermissiveAuthAdapter - Default adapter that allows all operations
+ *
+ * This adapter is used when no custom EntityAuthAdapter 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
+ */
+import { EntityAuthAdapter, type AuthUser } from './EntityAuthAdapter'
+
+export class PermissiveAuthAdapter extends EntityAuthAdapter {
+  /**
+   * Always allows any action on any entity type
+   */
+  canPerform(_entity: string, _action: string): boolean {
+    return true
+  }
+
+  /**
+   * Always allows access to any record
+   */
+  canAccessRecord(_entity: string, _record: unknown): boolean {
+    return true
+  }
+
+  /**
+   * Returns null (no authenticated user in permissive mode)
+   */
+  getCurrentUser(): AuthUser | null {
+    return null
+  }
+}
+
+/**
+ * Factory function to create a PermissiveAuthAdapter
+ */
+export function createPermissiveAdapter(): PermissiveAuthAdapter {
+  return new PermissiveAuthAdapter()
+}