s3db.js 13.4.0 → 13.6.0

package/src/plugins/api/auth/path-auth-matcher.js

@@ -0,0 +1,284 @@
+/**
+ * Path-based Authentication Matcher
+ *
+ * Provides path-specific authentication rules with precedence by specificity.
+ * More specific paths override less specific ones.
+ *
+ * @example
+ * const rules = [
+ *   { path: '/app/**', methods: ['oidc'], required: true },
+ *   { path: '/api/v1/**', methods: ['basic', 'oidc'], required: true },
+ *   { path: '/health', methods: [], required: false },
+ *   { path: '/**', methods: [], required: false } // default
+ * ];
+ *
+ * const rule = findAuthRule('/app/dashboard', rules);
+ * // => { path: '/app/**', methods: ['oidc'], required: true }
+ */
+
+/**
+ * Calculate path specificity score (higher = more specific)
+ * @param {string} pattern - Path pattern with wildcards
+ * @returns {number} Specificity score
+ */
+function calculateSpecificity(pattern) {
+  let score = 0;
+
+  // Exact matches (no wildcards) are most specific
+  if (!pattern.includes('*') && !pattern.includes(':')) {
+    score += 10000;
+  }
+
+  // Count path segments (more segments = more specific)
+  const segments = pattern.split('/').filter(s => s.length > 0);
+  score += segments.length * 100;
+
+  // Penalize wildcards (fewer wildcards = more specific)
+  const singleWildcards = (pattern.match(/(?<!\*)\*(?!\*)/g) || []).length;
+  const doubleWildcards = (pattern.match(/\*\*/g) || []).length;
+  score -= singleWildcards * 10;
+  score -= doubleWildcards * 50;
+
+  // Penalize route params (e.g., :id)
+  const params = (pattern.match(/:[^/]+/g) || []).length;
+  score -= params * 5;
+
+  return score;
+}
+
+/**
+ * Convert glob pattern to regex
+ * @param {string} pattern - Glob pattern
+ * @returns {RegExp} Regular expression
+ */
+function patternToRegex(pattern) {
+  // Escape special regex characters except * and :
+  let regexPattern = pattern
+    .replace(/[.+?^${}()|[\]\\]/g, '\\$&');
+
+  // Handle route params (:id, :userId, etc.)
+  regexPattern = regexPattern.replace(/:([^/]+)/g, '([^/]+)');
+
+  // Handle wildcards
+  regexPattern = regexPattern
+    .replace(/\*\*/g, '___GLOBSTAR___')  // Temporary placeholder
+    .replace(/\*/g, '[^/]*')              // * matches anything except /
+    .replace(/___GLOBSTAR___/g, '.*');    // ** matches everything including /
+
+  // Special case: if pattern ends with /**, it should match with or without trailing content
+  // e.g., /app/** should match both /app and /app/dashboard
+  if (pattern.endsWith('/**')) {
+    // Remove the /.*$ part and make it optional
+    regexPattern = regexPattern.replace(/\/\.\*$/, '(?:/.*)?');
+  }
+
+  // Anchor to start and end
+  regexPattern = '^' + regexPattern + '$';
+
+  return new RegExp(regexPattern);
+}
+
+/**
+ * Check if path matches pattern
+ * @param {string} path - Request path
+ * @param {string} pattern - Path pattern with wildcards
+ * @returns {boolean} True if matches
+ */
+export function matchPath(path, pattern) {
+  // Exact match (fast path)
+  if (path === pattern) return true;
+
+  // Regex match
+  const regex = patternToRegex(pattern);
+  return regex.test(path);
+}
+
+/**
+ * Find matching auth rule for path (most specific wins)
+ * @param {string} path - Request path
+ * @param {Array<Object>} rules - Auth rules
+ * @param {string} rules[].path - Path pattern
+ * @param {Array<string>} rules[].methods - Allowed auth methods
+ * @param {boolean} rules[].required - If true, auth is required
+ * @param {string} rules[].strategy - Auth strategy ('any' or 'priority')
+ * @param {Object} rules[].priorities - Priority map for 'priority' strategy
+ * @returns {Object|null} Matching rule or null
+ */
+export function findAuthRule(path, rules = []) {
+  if (!rules || rules.length === 0) {
+    return null;
+  }
+
+  // Find all matching rules
+  const matches = rules
+    .map(rule => ({
+      ...rule,
+      specificity: calculateSpecificity(rule.path)
+    }))
+    .filter(rule => matchPath(path, rule.path))
+    .sort((a, b) => b.specificity - a.specificity); // Highest specificity first
+
+  // Return most specific match
+  return matches.length > 0 ? matches[0] : null;
+}
+
+/**
+ * Create path-based auth middleware
+ * @param {Object} options - Middleware options
+ * @param {Array<Object>} options.rules - Path-based auth rules
+ * @param {Object} options.authMiddlewares - Available auth middlewares by name
+ * @param {Function} options.unauthorizedHandler - Handler for unauthorized requests
+ * @returns {Function} Hono middleware
+ */
+export function createPathBasedAuthMiddleware(options = {}) {
+  const {
+    rules = [],
+    authMiddlewares = {},
+    unauthorizedHandler = null,
+    events = null
+  } = options;
+
+  return async (c, next) => {
+    const currentPath = c.req.path;
+
+    // Find matching rule
+    const rule = findAuthRule(currentPath, rules);
+
+    // No rule = no auth required (default public)
+    if (!rule) {
+      return await next();
+    }
+
+    // Rule says auth not required = public
+    if (!rule.required) {
+      return await next();
+    }
+
+    // Rule says auth required but no methods = error in config
+    if (rule.methods.length === 0 && rule.required) {
+      console.error(`[Path Auth] Invalid rule: path "${rule.path}" requires auth but has no methods`);
+      if (unauthorizedHandler) {
+        return unauthorizedHandler(c, 'Configuration error');
+      }
+      return c.json({ error: 'Configuration error' }, 500);
+    }
+
+    // Get allowed auth middlewares for this path
+    const allowedMiddlewares = rule.methods
+      .map(methodName => ({
+        name: methodName,
+        middleware: authMiddlewares[methodName]
+      }))
+      .filter(m => m.middleware);
+
+    if (allowedMiddlewares.length === 0) {
+      console.error(`[Path Auth] No middlewares found for methods: ${rule.methods.join(', ')}`);
+      if (unauthorizedHandler) {
+        return unauthorizedHandler(c, 'No auth methods available');
+      }
+      return c.json({ error: 'No auth methods available' }, 500);
+    }
+
+    // Sort by priority if strategy is 'priority'
+    const strategy = rule.strategy || 'any';
+    const priorities = rule.priorities || {};
+
+    if (strategy === 'priority' && Object.keys(priorities).length > 0) {
+      allowedMiddlewares.sort((a, b) => {
+        const priorityA = priorities[a.name] || 999;
+        const priorityB = priorities[b.name] || 999;
+        return priorityA - priorityB; // Lower number = higher priority
+      });
+    }
+
+    // Try each auth method
+    for (const { name, middleware } of allowedMiddlewares) {
+      let authSuccess = false;
+      const tempNext = async () => {
+        authSuccess = true;
+      };
+
+      // Try auth method
+      await middleware(c, tempNext);
+
+      // If auth succeeded, continue
+      if (authSuccess && c.get('user')) {
+        // Emit auth:success event
+        if (events) {
+          events.emitAuthEvent('success', {
+            method: name,
+            user: c.get('user'),
+            path: currentPath,
+            rule: rule.path
+          });
+        }
+        return await next();
+      }
+    }
+
+    // Emit auth:failure event
+    if (events) {
+      events.emitAuthEvent('failure', {
+        path: currentPath,
+        rule: rule.path,
+        allowedMethods: rule.methods,
+        ip: c.req.header('x-forwarded-for') || c.req.header('x-real-ip')
+      });
+    }
+
+    // No auth method succeeded - apply content negotiation
+    const acceptHeader = c.req.header('accept') || '';
+    const acceptsHtml = acceptHeader.includes('text/html');
+
+    // Get unauthorized behavior from rule (default: 'auto')
+    const unauthorizedBehavior = rule.unauthorizedBehavior || 'auto';
+
+    // Auto mode: HTML → redirect, JSON → 401
+    if (unauthorizedBehavior === 'auto') {
+      if (acceptsHtml) {
+        // Browser request - redirect to login
+        const returnTo = encodeURIComponent(c.req.path);
+        return c.redirect(`/auth/login?returnTo=${returnTo}`);
+      } else {
+        // API request - return 401 JSON
+        return c.json({
+          error: 'Unauthorized',
+          message: `Authentication required. Allowed methods: ${rule.methods.join(', ')}`
+        }, 401);
+      }
+    }
+
+    // Custom behavior object: { html: 'redirect', json: { status: 401 } }
+    if (typeof unauthorizedBehavior === 'object') {
+      if (acceptsHtml && unauthorizedBehavior.html === 'redirect') {
+        const returnTo = encodeURIComponent(c.req.path);
+        const loginPath = unauthorizedBehavior.loginPath || '/auth/login';
+        return c.redirect(`${loginPath}?returnTo=${returnTo}`);
+      }
+
+      if (!acceptsHtml && unauthorizedBehavior.json) {
+        return c.json(
+          unauthorizedBehavior.json,
+          unauthorizedBehavior.json.status || 401
+        );
+      }
+    }
+
+    // Fallback: use custom handler or default 401
+    if (unauthorizedHandler) {
+      return unauthorizedHandler(c, `Authentication required. Allowed methods: ${rule.methods.join(', ')}`);
+    }
+
+    return c.json({
+      error: 'Unauthorized',
+      message: `Authentication required. Allowed methods: ${rule.methods.join(', ')}`
+    }, 401);
+  };
+}
+
+export default {
+  matchPath,
+  findAuthRule,
+  calculateSpecificity,
+  createPathBasedAuthMiddleware
+};

package/src/plugins/api/concerns/event-emitter.js

@@ -0,0 +1,134 @@
+/**
+ * API Event Emitter
+ *
+ * Provides event hooks throughout the API lifecycle for monitoring,
+ * analytics, and custom integrations.
+ *
+ * Supported Events:
+ * - user:created - New user created via OIDC
+ * - user:login - User logged in
+ * - auth:success - Authentication succeeded
+ * - auth:failure - Authentication failed
+ * - resource:created - Resource record created
+ * - resource:updated - Resource record updated
+ * - resource:deleted - Resource record deleted
+ * - request:start - Request started
+ * - request:end - Request ended
+ * - request:error - Request errored
+ *
+ * @example
+ * const events = new ApiEventEmitter();
+ *
+ * // Listen to user creation
+ * events.on('user:created', (data) => {
+ *   console.log('New user:', data.user);
+ * });
+ *
+ * // Listen to all resource changes
+ * events.on('resource:*', (data) => {
+ *   console.log('Resource event:', data.event, data.resource);
+ * });
+ *
+ * // Emit events
+ * events.emit('user:created', { user: userObject, source: 'oidc' });
+ */
+
+import { EventEmitter } from 'events';
+
+export class ApiEventEmitter extends EventEmitter {
+  constructor(options = {}) {
+    super();
+
+    this.options = {
+      enabled: options.enabled !== false, // Enabled by default
+      verbose: options.verbose || false,
+      maxListeners: options.maxListeners || 10
+    };
+
+    this.setMaxListeners(this.options.maxListeners);
+  }
+
+  /**
+   * Emit event with wildcard support
+   * @param {string} event - Event name
+   * @param {Object} data - Event data
+   */
+  emit(event, data = {}) {
+    if (!this.options.enabled) {
+      return false;
+    }
+
+    if (this.options.verbose) {
+      console.log(`[API Events] ${event}`, data);
+    }
+
+    // Emit specific event
+    super.emit(event, { event, ...data, timestamp: new Date().toISOString() });
+
+    // Emit wildcard pattern (e.g., "resource:*" for "resource:created")
+    if (event.includes(':')) {
+      const [prefix] = event.split(':');
+      const wildcardEvent = `${prefix}:*`;
+      super.emit(wildcardEvent, { event, ...data, timestamp: new Date().toISOString() });
+    }
+
+    return true;
+  }
+
+  /**
+   * Helper to emit user events
+   * @param {string} action - created, login, updated, deleted
+   * @param {Object} data - Event data
+   */
+  emitUserEvent(action, data) {
+    this.emit(`user:${action}`, data);
+  }
+
+  /**
+   * Helper to emit auth events
+   * @param {string} action - success, failure
+   * @param {Object} data - Event data
+   */
+  emitAuthEvent(action, data) {
+    this.emit(`auth:${action}`, data);
+  }
+
+  /**
+   * Helper to emit resource events
+   * @param {string} action - created, updated, deleted
+   * @param {Object} data - Event data
+   */
+  emitResourceEvent(action, data) {
+    this.emit(`resource:${action}`, data);
+  }
+
+  /**
+   * Helper to emit request events
+   * @param {string} action - start, end, error
+   * @param {Object} data - Event data
+   */
+  emitRequestEvent(action, data) {
+    this.emit(`request:${action}`, data);
+  }
+
+  /**
+   * Get event statistics
+   * @returns {Object} Event statistics
+   */
+  getStats() {
+    const stats = {
+      enabled: this.options.enabled,
+      maxListeners: this.options.maxListeners,
+      listeners: {}
+    };
+
+    // Count listeners per event
+    for (const event of this.eventNames()) {
+      stats.listeners[event] = this.listenerCount(event);
+    }
+
+    return stats;
+  }
+}
+
+export default ApiEventEmitter;