qdadm 0.31.0 → 0.32.0

package/src/entity/auth/CompositeAuthAdapter.js

@@ -0,0 +1,212 @@
+/**
+ * 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'
+ *
+ * @example
+ * ```js
+ * const composite = new CompositeAuthAdapter({
+ *   default: internalAuthAdapter,  // JWT for most entities
+ *   mapping: {
+ *     'products': apiKeyAdapter,    // API key for products
+ *     'external-*': externalAuth,   // OAuth for external-* entities
+ *     'readonly-*': readonlyAuth    // Read-only adapter
+ *   }
+ * })
+ *
+ * composite.canPerform('books', 'read')     // → uses default (internal)
+ * composite.canPerform('products', 'read')  // → uses apiKeyAdapter
+ * composite.canPerform('external-orders', 'read')  // → uses externalAuth
+ * ```
+ */
+
+import { AuthAdapter } from './AuthAdapter.js'
+import { authFactory } from './factory.js'
+
+export class CompositeAuthAdapter extends AuthAdapter {
+  /**
+   * @param {object} config - Composite auth configuration
+   * @param {AuthAdapter|string|object} config.default - Default adapter (required)
+   * @param {Object<string, AuthAdapter|string|object>} [config.mapping={}] - Entity pattern to adapter mapping
+   * @param {object} [context={}] - Factory context with authTypes
+   */
+  constructor(config, context = {}) {
+    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
+   *
+   * Resolution order:
+   * 1. Exact match in mapping
+   * 2. First matching glob pattern
+   * 3. Default adapter
+   *
+   * @param {string} entity - Entity name
+   * @returns {AuthAdapter}
+   */
+  _getAdapter(entity) {
+    // 1. Exact match
+    if (this._exactMatches.has(entity)) {
+      return this._exactMatches.get(entity)
+    }
+
+    // 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)
+   * Delegates to the appropriate adapter based on entity name
+   *
+   * @param {string} entity - Entity name
+   * @param {string} action - Action: read, create, update, delete, list
+   * @returns {boolean}
+   */
+  canPerform(entity, action) {
+    return this._getAdapter(entity).canPerform(entity, action)
+  }
+
+  /**
+   * Check if user can access specific record (silo check)
+   * Delegates to the appropriate adapter based on entity name
+   *
+   * @param {string} entity - Entity name
+   * @param {object} record - The record to check
+   * @returns {boolean}
+   */
+  canAccessRecord(entity, record) {
+    return this._getAdapter(entity).canAccessRecord(entity, record)
+  }
+
+  /**
+   * Get current user from the default adapter
+   * The "user" concept comes from the primary auth source
+   *
+   * @returns {object|null}
+   */
+  getCurrentUser() {
+    return this._default.getCurrentUser()
+  }
+
+  /**
+   * Check if user is granted an attribute (role or permission)
+   * Delegates to default adapter for global permissions
+   *
+   * @param {string} attribute - Role or permission to check
+   * @param {object} [subject] - Optional subject for context
+   * @returns {boolean}
+   */
+  isGranted(attribute, subject = null) {
+    // For entity-specific permissions (entity:action), route to appropriate adapter
+    if (attribute.includes(':') && !attribute.startsWith('ROLE_')) {
+      const [entity] = attribute.split(':')
+      const adapter = this._getAdapter(entity)
+      if (adapter.isGranted) {
+        return adapter.isGranted(attribute, subject)
+      }
+    }
+
+    // Global permissions use default adapter
+    if (this._default.isGranted) {
+      return this._default.isGranted(attribute, subject)
+    }
+
+    // Fallback for adapters without isGranted
+    return true
+  }
+
+  /**
+   * Get the default adapter
+   * @returns {AuthAdapter}
+   */
+  get defaultAdapter() {
+    return this._default
+  }
+
+  /**
+   * Get adapter info for debugging
+   * @returns {object}
+   */
+  getAdapterInfo() {
+    const info = {
+      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
+   * @private
+   */
+  _getAdapterName(adapter) {
+    return adapter.constructor?.name || 'Unknown'
+  }
+}
+
+/**
+ * Factory function to create CompositeAuthAdapter
+ *
+ * @param {object} config - { default, mapping }
+ * @param {object} [context] - Factory context
+ * @returns {CompositeAuthAdapter}
+ */
+export function createCompositeAuthAdapter(config, context = {}) {
+  return new CompositeAuthAdapter(config, context)
+}

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 { AuthAdapter } from './AuthAdapter.js'
+import { PermissiveAuthAdapter } from './PermissiveAdapter.js'
+
+/**
+ * Built-in auth adapter types
+ * Extended via context.authTypes for custom adapters
+ * @type {Record<string, typeof AuthAdapter>}
+ */
+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 {AuthAdapter} 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 {AuthAdapter | string | object} config - Auth config
+ * @param {object} [context={}] - Context with authTypes, authResolver
+ * @returns {AuthAdapter} 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 AuthAdapter instance → return directly (backward compatible)
+  if (config instanceof AuthAdapter) {
+    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 { AuthAdapter } from './AuthAdapter.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 AuthAdapter {
+  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 AuthAdapter {
+  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 AuthAdapter 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,6 +3,10 @@
  *
  * 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
@@ -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'