qdadm 0.31.0 → 0.34.0

package/src/entity/auth/factory.js

@@ -0,0 +1,207 @@
+/**
+ * Auth Factory/Resolver Pattern
+ *
+ * Enables declarative auth adapter configuration with auto-resolution.
+ * Follows the same pattern as storage/factory.js for consistency.
+ *
+ * IMPORTANT: Backward compatible - passing an AuthAdapter instance
+ * works exactly as before (simple passthrough).
+ *
+ * Usage:
+ * ```js
+ * // Instance passthrough (current behavior, unchanged)
+ * authFactory(myAdapter)  // → myAdapter
+ *
+ * // String pattern → factory resolves from registry
+ * authFactory('permissive')  // → PermissiveAuthAdapter
+ * authFactory('jwt:internal')  // → JwtAuthAdapter (if registered)
+ *
+ * // Config object → factory resolves
+ * authFactory({ type: 'jwt', tokenKey: 'auth_token' })
+ *
+ * // Composite config → creates CompositeAuthAdapter
+ * authFactory({
+ *   default: myAdapter,
+ *   mapping: { 'external-*': externalAdapter }
+ * })
+ * ```
+ */
+
+import { EntityAuthAdapter } from './EntityAuthAdapter.js'
+import { PermissiveAuthAdapter } from './PermissiveAdapter.js'
+
+/**
+ * Built-in auth adapter types
+ * Extended via context.authTypes for custom adapters
+ * @type {Record<string, typeof EntityAuthAdapter>}
+ */
+export const authTypes = {
+  permissive: PermissiveAuthAdapter
+}
+
+/**
+ * Parse auth pattern 'type' or 'type:scope'
+ *
+ * @param {string} pattern - Auth pattern (e.g., 'jwt', 'apikey:external')
+ * @returns {{type: string, scope?: string} | null} Parsed config or null
+ *
+ * @example
+ * parseAuthPattern('jwt')            // → { type: 'jwt' }
+ * parseAuthPattern('apikey:external') // → { type: 'apikey', scope: 'external' }
+ */
+export function parseAuthPattern(pattern) {
+  if (typeof pattern !== 'string') return null
+
+  const match = pattern.match(/^(\w+)(?::(.+))?$/)
+  if (match) {
+    const [, type, scope] = match
+    return scope ? { type, scope } : { type }
+  }
+  return null
+}
+
+/**
+ * Default auth resolver - creates adapter instance from config
+ *
+ * @param {object} config - Normalized auth config with `type` property
+ * @param {object} context - Context with authTypes registry
+ * @returns {EntityAuthAdapter} Adapter instance
+ */
+export function defaultAuthResolver(config, context = {}) {
+  const { type, ...rest } = config
+
+  // Merge built-in types with custom types from context
+  const allTypes = { ...authTypes, ...context.authTypes }
+  const AdapterClass = allTypes[type]
+
+  if (!AdapterClass) {
+    throw new Error(
+      `[authFactory] Unknown auth type: "${type}". ` +
+      `Available: ${Object.keys(allTypes).join(', ')}`
+    )
+  }
+
+  return new AdapterClass(rest)
+}
+
+/**
+ * Check if config is a composite auth config
+ * Composite config has 'default' + optional 'mapping'
+ *
+ * @param {any} config
+ * @returns {boolean}
+ */
+function isCompositeConfig(config) {
+  return (
+    config &&
+    typeof config === 'object' &&
+    'default' in config &&
+    !('type' in config)
+  )
+}
+
+/**
+ * Auth factory - normalizes input and resolves to adapter
+ *
+ * Handles:
+ * - AuthAdapter instance → return directly (backward compatible)
+ * - String pattern 'type' → parse and resolve
+ * - Config object with 'type' → resolve via registry
+ * - Config object with 'default' → create CompositeAuthAdapter
+ *
+ * @param {EntityAuthAdapter | string | object} config - Auth config
+ * @param {object} [context={}] - Context with authTypes, authResolver
+ * @returns {EntityAuthAdapter} Adapter instance
+ *
+ * @example
+ * // Instance passthrough (most common, backward compatible)
+ * authFactory(myAdapter)  // → myAdapter
+ *
+ * // String patterns
+ * authFactory('permissive')  // → PermissiveAuthAdapter
+ * authFactory('jwt')  // → JwtAuthAdapter (if registered)
+ *
+ * // Config objects
+ * authFactory({ type: 'jwt', tokenKey: 'token' })
+ *
+ * // Composite (multi-source)
+ * authFactory({
+ *   default: myAdapter,
+ *   mapping: { 'products': apiKeyAdapter }
+ * })
+ */
+export function authFactory(config, context = {}) {
+  const { authResolver = defaultAuthResolver } = context
+
+  // Null/undefined → permissive (safe default)
+  if (config == null) {
+    return new PermissiveAuthAdapter()
+  }
+
+  // Already an EntityAuthAdapter instance → return directly (backward compatible)
+  if (config instanceof EntityAuthAdapter) {
+    return config
+  }
+
+  // Duck-typed adapter (has canPerform method)
+  if (typeof config.canPerform === 'function') {
+    return config
+  }
+
+  // String pattern → parse and resolve
+  if (typeof config === 'string') {
+    const parsed = parseAuthPattern(config)
+    if (!parsed) {
+      throw new Error(`[authFactory] Invalid auth pattern: "${config}"`)
+    }
+    return authResolver(parsed, context)
+  }
+
+  // Config object
+  if (typeof config === 'object') {
+    // Composite config: { default: ..., mapping: { ... } }
+    // Handled separately to avoid circular dependency
+    // The CompositeAuthAdapter is resolved via authTypes registry
+    if (isCompositeConfig(config)) {
+      const CompositeClass = context.authTypes?.composite || context.CompositeAuthAdapter
+      if (!CompositeClass) {
+        throw new Error(
+          '[authFactory] Composite config requires CompositeAuthAdapter. ' +
+          'Pass it via context.CompositeAuthAdapter or register as context.authTypes.composite'
+        )
+      }
+      return new CompositeClass(config, context)
+    }
+
+    // Simple config with type: { type: 'jwt', ... }
+    if (config.type) {
+      return authResolver(config, context)
+    }
+
+    throw new Error(
+      '[authFactory] Config object requires either "type" or "default" property'
+    )
+  }
+
+  throw new Error(
+    `[authFactory] Invalid auth config: ${typeof config}. ` +
+    'Expected AuthAdapter instance, string, or config object.'
+  )
+}
+
+/**
+ * Create a custom auth factory with bound context
+ *
+ * @param {object} context - Context with authTypes, authResolver
+ * @returns {function} Auth factory with bound context
+ *
+ * @example
+ * const myAuthFactory = createAuthFactory({
+ *   authTypes: { jwt: JwtAuthAdapter, apikey: ApiKeyAuthAdapter }
+ * })
+ *
+ * const adapter = myAuthFactory('jwt')
+ */
+export function createAuthFactory(context) {
+  return (config) => authFactory(config, context)
+}

package/src/entity/auth/factory.test.js

@@ -0,0 +1,257 @@
+/**
+ * Tests for auth factory and CompositeAuthAdapter
+ */
+import { describe, it, expect } from 'vitest'
+import { EntityAuthAdapter } from './EntityAuthAdapter.js'
+import { PermissiveAuthAdapter } from './PermissiveAdapter.js'
+import { CompositeAuthAdapter } from './CompositeAuthAdapter.js'
+import { authFactory, parseAuthPattern, authTypes } from './factory.js'
+
+// Test adapter for custom types
+class TestAuthAdapter extends EntityAuthAdapter {
+  constructor(options = {}) {
+    super()
+    this.options = options
+  }
+  canPerform() { return true }
+  canAccessRecord() { return true }
+  getCurrentUser() { return { id: 'test' } }
+}
+
+// Adapter that tracks which entity was checked
+class TrackingAdapter extends EntityAuthAdapter {
+  constructor(name) {
+    super()
+    this.name = name
+    this.checkedEntities = []
+  }
+  canPerform(entity, action) {
+    this.checkedEntities.push({ entity, action })
+    return true
+  }
+  canAccessRecord() { return true }
+  getCurrentUser() { return { name: this.name } }
+}
+
+describe('parseAuthPattern', () => {
+  it('parses simple type', () => {
+    expect(parseAuthPattern('jwt')).toEqual({ type: 'jwt' })
+    expect(parseAuthPattern('permissive')).toEqual({ type: 'permissive' })
+  })
+
+  it('parses type with scope', () => {
+    expect(parseAuthPattern('jwt:internal')).toEqual({ type: 'jwt', scope: 'internal' })
+    expect(parseAuthPattern('apikey:external')).toEqual({ type: 'apikey', scope: 'external' })
+  })
+
+  it('returns null for invalid input', () => {
+    expect(parseAuthPattern(null)).toBeNull()
+    expect(parseAuthPattern(123)).toBeNull()
+    expect(parseAuthPattern('')).toBeNull()
+  })
+})
+
+describe('authFactory', () => {
+  describe('instance passthrough', () => {
+    it('returns EntityAuthAdapter instance as-is', () => {
+      const adapter = new PermissiveAuthAdapter()
+      const result = authFactory(adapter)
+      expect(result).toBe(adapter)
+    })
+
+    it('returns duck-typed adapter as-is', () => {
+      const duckAdapter = {
+        canPerform: () => true,
+        canAccessRecord: () => true,
+        getCurrentUser: () => null
+      }
+      const result = authFactory(duckAdapter)
+      expect(result).toBe(duckAdapter)
+    })
+  })
+
+  describe('null/undefined', () => {
+    it('returns PermissiveAuthAdapter for null', () => {
+      const result = authFactory(null)
+      expect(result).toBeInstanceOf(PermissiveAuthAdapter)
+    })
+
+    it('returns PermissiveAuthAdapter for undefined', () => {
+      const result = authFactory(undefined)
+      expect(result).toBeInstanceOf(PermissiveAuthAdapter)
+    })
+  })
+
+  describe('string patterns', () => {
+    it('resolves built-in types', () => {
+      const result = authFactory('permissive')
+      expect(result).toBeInstanceOf(PermissiveAuthAdapter)
+    })
+
+    it('resolves custom types from context', () => {
+      const result = authFactory('test', {
+        authTypes: { test: TestAuthAdapter }
+      })
+      expect(result).toBeInstanceOf(TestAuthAdapter)
+    })
+
+    it('throws for unknown type', () => {
+      expect(() => authFactory('unknown')).toThrow(/Unknown auth type/)
+    })
+  })
+
+  describe('config objects', () => {
+    it('resolves config with type', () => {
+      const result = authFactory(
+        { type: 'test', foo: 'bar' },
+        { authTypes: { test: TestAuthAdapter } }
+      )
+      expect(result).toBeInstanceOf(TestAuthAdapter)
+      expect(result.options.foo).toBe('bar')
+    })
+
+    it('throws for config without type or default', () => {
+      expect(() => authFactory({ foo: 'bar' })).toThrow(/requires either "type" or "default"/)
+    })
+  })
+
+  describe('composite config', () => {
+    it('creates CompositeAuthAdapter from config', () => {
+      const defaultAdapter = new PermissiveAuthAdapter()
+      const result = authFactory(
+        { default: defaultAdapter },
+        { CompositeAuthAdapter }
+      )
+      expect(result).toBeInstanceOf(CompositeAuthAdapter)
+    })
+
+    it('throws without CompositeAuthAdapter in context', () => {
+      const defaultAdapter = new PermissiveAuthAdapter()
+      expect(() => authFactory({ default: defaultAdapter })).toThrow(/CompositeAuthAdapter/)
+    })
+  })
+})
+
+describe('CompositeAuthAdapter', () => {
+  describe('routing', () => {
+    it('uses default adapter for unmatched entities', () => {
+      const defaultAdapter = new TrackingAdapter('default')
+      const composite = new CompositeAuthAdapter({ default: defaultAdapter })
+
+      composite.canPerform('books', 'read')
+      composite.canPerform('users', 'create')
+
+      expect(defaultAdapter.checkedEntities).toEqual([
+        { entity: 'books', action: 'read' },
+        { entity: 'users', action: 'create' }
+      ])
+    })
+
+    it('routes exact matches to mapped adapter', () => {
+      const defaultAdapter = new TrackingAdapter('default')
+      const productsAdapter = new TrackingAdapter('products')
+
+      const composite = new CompositeAuthAdapter({
+        default: defaultAdapter,
+        mapping: { products: productsAdapter }
+      })
+
+      composite.canPerform('books', 'read')
+      composite.canPerform('products', 'read')
+
+      expect(defaultAdapter.checkedEntities).toHaveLength(1)
+      expect(defaultAdapter.checkedEntities[0].entity).toBe('books')
+
+      expect(productsAdapter.checkedEntities).toHaveLength(1)
+      expect(productsAdapter.checkedEntities[0].entity).toBe('products')
+    })
+
+    it('routes glob patterns to mapped adapter', () => {
+      const defaultAdapter = new TrackingAdapter('default')
+      const externalAdapter = new TrackingAdapter('external')
+
+      const composite = new CompositeAuthAdapter({
+        default: defaultAdapter,
+        mapping: { 'external-*': externalAdapter }
+      })
+
+      composite.canPerform('books', 'read')
+      composite.canPerform('external-products', 'read')
+      composite.canPerform('external-orders', 'list')
+
+      expect(defaultAdapter.checkedEntities).toHaveLength(1)
+      expect(externalAdapter.checkedEntities).toHaveLength(2)
+    })
+
+    it('supports suffix glob patterns', () => {
+      const defaultAdapter = new TrackingAdapter('default')
+      const readonlyAdapter = new TrackingAdapter('readonly')
+
+      const composite = new CompositeAuthAdapter({
+        default: defaultAdapter,
+        mapping: { '*-readonly': readonlyAdapter }
+      })
+
+      composite.canPerform('products-readonly', 'read')
+      composite.canPerform('products', 'read')
+
+      expect(readonlyAdapter.checkedEntities).toHaveLength(1)
+      expect(defaultAdapter.checkedEntities).toHaveLength(1)
+    })
+  })
+
+  describe('getCurrentUser', () => {
+    it('returns user from default adapter', () => {
+      const defaultAdapter = new TrackingAdapter('admin')
+      const externalAdapter = new TrackingAdapter('service')
+
+      const composite = new CompositeAuthAdapter({
+        default: defaultAdapter,
+        mapping: { 'external-*': externalAdapter }
+      })
+
+      expect(composite.getCurrentUser()).toEqual({ name: 'admin' })
+    })
+  })
+
+  describe('factory integration', () => {
+    it('resolves adapters in mapping via factory', () => {
+      const defaultAdapter = new PermissiveAuthAdapter()
+
+      const composite = new CompositeAuthAdapter(
+        {
+          default: defaultAdapter,
+          mapping: {
+            products: { type: 'test' }
+          }
+        },
+        { authTypes: { test: TestAuthAdapter } }
+      )
+
+      // Products should use TestAuthAdapter
+      expect(composite._getAdapter('products')).toBeInstanceOf(TestAuthAdapter)
+      // Others use default
+      expect(composite._getAdapter('books')).toBe(defaultAdapter)
+    })
+  })
+
+  describe('getAdapterInfo', () => {
+    it('returns debug info about adapters', () => {
+      const composite = new CompositeAuthAdapter({
+        default: new PermissiveAuthAdapter(),
+        mapping: {
+          products: new TestAuthAdapter(),
+          'external-*': new TrackingAdapter('ext')
+        }
+      })
+
+      const info = composite.getAdapterInfo()
+
+      expect(info.default).toBe('PermissiveAuthAdapter')
+      expect(info.exactMatches.products).toBe('TestAuthAdapter')
+      expect(info.patterns).toHaveLength(1)
+      expect(info.patterns[0].pattern).toBe('external-*')
+      expect(info.patterns[0].adapter).toBe('TrackingAdapter')
+    })
+  })
+})

package/src/entity/auth/index.js

@@ -3,10 +3,14 @@
  *
  * AuthAdapter interface and implementations for scope/silo permission checks.
  * Includes Symfony-inspired role hierarchy and security checker.
+ *
+ * Multi-source auth:
+ * - CompositeAuthAdapter routes to different adapters based on entity patterns
+ * - authFactory normalizes config (instance, string, or object)
  */
 
 // Interface
-export { AuthAdapter, AuthActions } from './AuthAdapter.js'
+export { EntityAuthAdapter, AuthActions } from './EntityAuthAdapter.js'
 
 // Role Hierarchy (topological resolution)
 export { RoleHierarchy, createRoleHierarchy } from './RoleHierarchy.js'
@@ -16,3 +20,13 @@ export { SecurityChecker, createSecurityChecker } from './SecurityChecker.js'
 
 // Implementations
 export { PermissiveAuthAdapter, createPermissiveAdapter } from './PermissiveAdapter.js'
+export { CompositeAuthAdapter, createCompositeAuthAdapter } from './CompositeAuthAdapter.js'
+
+// Factory/Resolver pattern (like storage/factory.js)
+export {
+  authFactory,
+  createAuthFactory,
+  authTypes,
+  parseAuthPattern,
+  defaultAuthResolver
+} from './factory.js'

package/src/entity/storage/MockApiStorage.js

@@ -65,13 +65,26 @@ export class MockApiStorage extends IStorage {
     return MockApiStorage.capabilities.supportsCaching
   }
 
+  /**
+   * Instance capabilities getter.
+   * Merges static capabilities with instance-specific ones like requiresAuth.
+   * @returns {object}
+   */
+  get capabilities() {
+    return {
+      ...MockApiStorage.capabilities,
+      requiresAuth: !!this._authCheck
+    }
+  }
+
   constructor(options = {}) {
     super()
     const {
       entityName,
       idField = 'id',
       generateId = () => Date.now().toString(36) + Math.random().toString(36).substr(2),
-      initialData = null
+      initialData = null,
+      authCheck = null // Optional: () => boolean - throws 401 if returns false
     } = options
 
     if (!entityName) {
@@ -83,11 +96,24 @@ export class MockApiStorage extends IStorage {
     this.generateId = generateId
     this._storageKey = `mockapi_${entityName}_data`
     this._data = new Map()
+    this._authCheck = authCheck
 
     // Load from localStorage or seed with initialData
     this._loadFromStorage(initialData)
   }
 
+  /**
+   * Check authentication if authCheck is configured
+   * @throws {Error} 401 error if not authenticated
+   */
+  _checkAuth() {
+    if (this._authCheck && !this._authCheck()) {
+      const error = new Error(`Unauthorized: Authentication required to access ${this.entityName}`)
+      error.status = 401
+      throw error
+    }
+  }
+
   /**
    * Load data from localStorage, seed with initialData if empty
    * @param {Array|null} initialData - Data to seed if storage is empty
@@ -158,6 +184,7 @@ export class MockApiStorage extends IStorage {
    * @returns {Promise<{ items: Array, total: number }>}
    */
   async list(params = {}) {
+    this._checkAuth()
     const { page = 1, page_size = 20, sort_by, sort_order = 'asc', filters = {}, search } = params
 
     let items = this._getAll()
@@ -213,6 +240,7 @@ export class MockApiStorage extends IStorage {
    * @returns {Promise<object>}
    */
   async get(id) {
+    this._checkAuth()
     const item = this._data.get(String(id))
     if (!item) {
       const error = new Error(`Entity not found: ${id}`)
@@ -228,6 +256,7 @@ export class MockApiStorage extends IStorage {
    * @returns {Promise<Array<object>>}
    */
   async getMany(ids) {
+    this._checkAuth()
     if (!ids || ids.length === 0) return []
     const results = []
     for (const id of ids) {
@@ -282,6 +311,7 @@ export class MockApiStorage extends IStorage {
    * @returns {Promise<object>}
    */
   async create(data) {
+    this._checkAuth()
     const id = data[this.idField] || this.generateId()
     const newItem = {
       ...data,
@@ -300,6 +330,7 @@ export class MockApiStorage extends IStorage {
    * @returns {Promise<object>}
    */
   async update(id, data) {
+    this._checkAuth()
     if (!this._data.has(String(id))) {
       const error = new Error(`Entity not found: ${id}`)
       error.status = 404
@@ -322,6 +353,7 @@ export class MockApiStorage extends IStorage {
    * @returns {Promise<object>}
    */
   async patch(id, data) {
+    this._checkAuth()
     const existing = this._data.get(String(id))
     if (!existing) {
       const error = new Error(`Entity not found: ${id}`)
@@ -344,6 +376,7 @@ export class MockApiStorage extends IStorage {
    * @returns {Promise<void>}
    */
   async delete(id) {
+    this._checkAuth()
     if (!this._data.has(String(id))) {
       const error = new Error(`Entity not found: ${id}`)
       error.status = 404

package/src/index.js

@@ -17,6 +17,9 @@ export { createQdadm } from './plugin.js'
 // Entity system
 export * from './entity/index.js'
 
+// Session auth (user authentication)
+export * from './auth/index.js'
+
 // Orchestrator
 export * from './orchestrator/index.js'