webspresso 0.0.90 → 0.0.91

package/plugins/basic-auth/index.js

@@ -0,0 +1,293 @@
+/**
+ * Basic Auth Plugin — HTTP Basic Authentication (RFC 7617) for Webspresso
+ * Zero external dependencies (uses native Node.js crypto for timing-safe equality)
+ * @module plugins/basic-auth
+ */
+
+const crypto = require('crypto');
+
+/**
+ * Compare two strings in constant time to prevent timing attacks.
+ * Uses dummy buffer comparison if lengths differ to avoid leaking length via response timing.
+ * 
+ * @param {string} a
+ * @param {string} b
+ * @returns {boolean}
+ */
+function safeCompare(a, b) {
+  if (typeof a !== 'string' || typeof b !== 'string') {
+    return false;
+  }
+
+  const bufA = Buffer.from(a, 'utf8');
+  const bufB = Buffer.from(b, 'utf8');
+
+  if (bufA.length !== bufB.length) {
+    // Perform dummy timing-safe comparison with itself to preserve constant execution time
+    crypto.timingSafeEqual(bufA, bufA);
+    return false;
+  }
+
+  return crypto.timingSafeEqual(bufA, bufB);
+}
+
+/**
+ * Parse an HTTP Authorization header for Basic credentials.
+ * 
+ * @param {string} header - e.g. "Basic dXNlcjpwYXNz"
+ * @returns {{ username: string, password: string } | null}
+ */
+function parseBasicAuthHeader(header) {
+  if (!header || typeof header !== 'string') {
+    return null;
+  }
+
+  const parts = header.trim().split(/\s+/);
+  if (parts.length !== 2 || parts[0].toLowerCase() !== 'basic') {
+    return null;
+  }
+
+  try {
+    const decoded = Buffer.from(parts[1], 'base64').toString('utf8');
+    const colonIndex = decoded.indexOf(':');
+    if (colonIndex === -1) {
+      return null;
+    }
+
+    const username = decoded.slice(0, colonIndex);
+    const password = decoded.slice(colonIndex + 1);
+    return { username, password };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Extract credentials from request Authorization header or proxy headers
+ * 
+ * @param {import('express').Request} req
+ * @returns {{ username: string, password: string } | null}
+ */
+function extractCredentials(req) {
+  const header = req.headers.authorization || req.headers.Authorization;
+  return parseBasicAuthHeader(header);
+}
+
+/**
+ * Check if request matches path prefix list
+ * 
+ * @param {string} path
+ * @param {string|string[]|boolean} routes
+ * @returns {boolean}
+ */
+function shouldApplyToRoute(path, routes) {
+  if (routes === true || routes == null) return true;
+  const list = Array.isArray(routes) ? routes : [routes];
+  return list.some((prefix) => path.startsWith(prefix));
+}
+
+/**
+ * Check if request path should be skipped
+ * 
+ * @param {import('express').Request} req
+ * @param {string[]} skipPaths
+ * @param {Function} [skipFn]
+ * @returns {boolean}
+ */
+function isSkipped(req, skipPaths = [], skipFn) {
+  if (typeof skipFn === 'function' && skipFn(req)) {
+    return true;
+  }
+  const p = req.path || req.url || '';
+  if (Array.isArray(skipPaths) && skipPaths.some((prefix) => p.startsWith(prefix))) {
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Send 401 Unauthorized response with optional Basic challenge header
+ * 
+ * @param {import('express').Request} req
+ * @param {import('express').Response} res
+ * @param {Object} config
+ */
+function sendUnauthorized(req, res, config) {
+  res.statusCode = 401;
+
+  if (config.challenge !== false) {
+    const realm = String(config.realm || 'Restricted Area')
+      .split(/[\r\n]/)[0]
+      .replace(/"/g, '\\"');
+    res.setHeader('WWW-Authenticate', `Basic realm="${realm}"`);
+  }
+
+  if (typeof config.unauthorizedResponse === 'function') {
+    return config.unauthorizedResponse(req, res);
+  }
+
+  if (config.unauthorizedResponse && typeof config.unauthorizedResponse === 'object') {
+    res.setHeader('Content-Type', 'application/json; charset=utf-8');
+    return res.end(JSON.stringify(config.unauthorizedResponse));
+  }
+
+  if (typeof config.unauthorizedResponse === 'string') {
+    res.setHeader('Content-Type', 'text/plain; charset=utf-8');
+    return res.end(config.unauthorizedResponse);
+  }
+
+  const acceptsJson = req.headers.accept && req.headers.accept.includes('application/json');
+  if (acceptsJson) {
+    res.setHeader('Content-Type', 'application/json; charset=utf-8');
+    return res.end(JSON.stringify({ error: 'Unauthorized', message: 'Authentication required.' }));
+  }
+
+  res.setHeader('Content-Type', 'text/plain; charset=utf-8');
+  res.end('Unauthorized');
+}
+
+/**
+ * Create Basic Auth Express middleware
+ * 
+ * @param {Object} [options]
+ * @param {Record<string, string>} [options.users] - Static username-password map
+ * @param {Function} [options.verify] - Custom verification function (username, password, req) => boolean | object | Promise<boolean | object>
+ * @param {string} [options.realm='Restricted Area'] - Realm name in WWW-Authenticate header
+ * @param {boolean} [options.challenge=true] - Whether to send WWW-Authenticate challenge header
+ * @param {string|string[]|boolean} [options.routes=true] - Route prefixes to protect (used in global mode)
+ * @param {string[]} [options.skipPaths] - Array of path prefixes to skip authentication
+ * @param {Function} [options.skip] - Custom predicate function (req) => boolean
+ * @param {Function|string|Object} [options.unauthorizedResponse] - Custom 401 response
+ * @param {Function} [options.onAuthenticated] - Callback hook (req, user) => void
+ * @returns {Function} Express middleware handler
+ */
+function createBasicAuthMiddleware(options = {}) {
+  const config = {
+    realm: 'Restricted Area',
+    challenge: true,
+    routes: true,
+    skipPaths: [],
+    ...options,
+  };
+
+  return async (req, res, next) => {
+    const reqPath = req.path || req.url || '/';
+
+    if (!shouldApplyToRoute(reqPath, config.routes)) {
+      return next();
+    }
+
+    if (isSkipped(req, config.skipPaths, config.skip)) {
+      return next();
+    }
+
+    const credentials = extractCredentials(req);
+    if (!credentials) {
+      return sendUnauthorized(req, res, config);
+    }
+
+    const { username, password } = credentials;
+    let authResult = false;
+
+    if (typeof config.verify === 'function') {
+      try {
+        authResult = await config.verify(username, password, req);
+      } catch (err) {
+        return next(err);
+      }
+    } else if (config.users && typeof config.users === 'object') {
+      const expectedPassword = config.users[username];
+      if (typeof expectedPassword === 'string') {
+        authResult = safeCompare(password, expectedPassword);
+      }
+    }
+
+    if (!authResult) {
+      return sendUnauthorized(req, res, config);
+    }
+
+    // Attach authentication context to request
+    req.basicAuth = { username };
+    req.auth = req.auth || {};
+    const userObj = typeof authResult === 'object' && authResult !== null
+      ? authResult
+      : { username, type: 'basic' };
+
+    req.auth.user = userObj;
+    if (!req.user) {
+      req.user = userObj;
+    }
+
+    if (typeof config.onAuthenticated === 'function') {
+      try {
+        config.onAuthenticated(req, userObj);
+      } catch (err) {
+        return next(err);
+      }
+    }
+
+    next();
+  };
+}
+
+/**
+ * Webspresso Basic Auth Plugin Factory
+ * 
+ * @param {Object} [options] - Plugin configuration options
+ * @param {boolean} [options.global=false] - Whether to apply basic auth as a global middleware on the app
+ * @param {Record<string, string>} [options.users] - Default static username-password dictionary
+ * @param {Function} [options.verify] - Default custom verification function
+ * @param {string} [options.realm='Restricted Area'] - Default realm name
+ * @param {boolean} [options.challenge=true] - Default challenge header flag
+ * @param {string|string[]|boolean} [options.routes=true] - Route prefixes (when global: true)
+ * @param {string[]} [options.skipPaths] - Default skip path prefixes
+ * @param {Function} [options.skip] - Default skip predicate function
+ * @param {Function|string|Object} [options.unauthorizedResponse] - Custom 401 response
+ * @param {Function} [options.onAuthenticated] - Callback hook on successful login
+ * @returns {Object} Webspresso Plugin Definition
+ */
+function basicAuthPlugin(options = {}) {
+  const { global: applyGlobal = false, ...pluginDefaults } = options;
+
+  return {
+    name: 'basic-auth',
+    version: '1.0.0',
+    description: 'HTTP Basic Authentication (RFC 7617) plugin with named middleware and global guard',
+    options,
+
+    api: {
+      createMiddleware: (routeOpts = {}) =>
+        createBasicAuthMiddleware({ ...pluginDefaults, ...routeOpts }),
+      parseHeader: parseBasicAuthHeader,
+      safeCompare,
+      extractCredentials,
+    },
+
+    register(ctx) {
+      // Register named middleware factory for file routes: middleware: ['basicAuth'] or [['basicAuth', { ... }]]
+      if (ctx.middlewares) {
+        ctx.middlewares.basicAuth = (routeOpts = {}) =>
+          createBasicAuthMiddleware({ ...pluginDefaults, ...routeOpts });
+      }
+
+      // Mount global middleware if global: true
+      if (applyGlobal && ctx.app) {
+        const globalMw = createBasicAuthMiddleware(options);
+        ctx.app.use(globalMw);
+      }
+    },
+  };
+}
+
+basicAuthPlugin.basicAuthPlugin = basicAuthPlugin;
+basicAuthPlugin.createBasicAuthMiddleware = createBasicAuthMiddleware;
+basicAuthPlugin.parseBasicAuthHeader = parseBasicAuthHeader;
+basicAuthPlugin.safeCompare = safeCompare;
+basicAuthPlugin.extractCredentials = extractCredentials;
+
+module.exports = basicAuthPlugin;
+module.exports.basicAuthPlugin = basicAuthPlugin;
+module.exports.createBasicAuthMiddleware = createBasicAuthMiddleware;
+module.exports.parseBasicAuthHeader = parseBasicAuthHeader;
+module.exports.safeCompare = safeCompare;
+module.exports.extractCredentials = extractCredentials;

package/plugins/data-exchange/export-xlsx.js

@@ -15,7 +15,11 @@ const { resolveExportRecords } = require('./record-selection');
 async function buildXlsxBuffer(model, records) {
   const clean = sanitizeForOutput(records, model);
   const hiddenSet = new Set(model.hidden || []);
-  const columns = Array.from(model.columns.keys()).filter((c) => !hiddenSet.has(c));
+  const columns = (model.columns && model.columns.size > 0)
+    ? Array.from(model.columns.keys()).filter((c) => !hiddenSet.has(c))
+    : (model.schema?.shape
+        ? Object.keys(model.schema.shape).filter((c) => !hiddenSet.has(c))
+        : Object.keys(clean[0] || {}));
 
   const wb = new ExcelJS.Workbook();
   const ws = wb.addWorksheet('Export', {

package/plugins/data-exchange/import.js

@@ -10,7 +10,13 @@ const { buildHeaderMapping, dataRowsToObjects } = require('./parse-table');
 
 function allowedImportColumns(model) {
   const hidden = new Set(model.hidden || []);
-  return Array.from(model.columns.keys()).filter((c) => !hidden.has(c));
+  if (model.columns && model.columns.size > 0) {
+    return Array.from(model.columns.keys()).filter((c) => !hidden.has(c));
+  }
+  if (model.schema && model.schema.shape) {
+    return Object.keys(model.schema.shape).filter((c) => !hidden.has(c));
+  }
+  return [];
 }
 
 /**
@@ -28,7 +34,15 @@ function coerceCell(raw, meta, column) {
     raw = t;
   }
 
-  if (!meta || !meta.type) return raw;
+  if (!meta || !meta.type) {
+    if (raw === 'true' || raw === '1' || raw === 'yes') return true;
+    if (raw === 'false' || raw === '0' || raw === 'no') return false;
+    if (typeof raw === 'string' && /^-?\d+(\.\d+)?$/.test(raw)) {
+      const num = Number(raw);
+      if (!Number.isNaN(num)) return num;
+    }
+    return raw;
+  }
 
   switch (meta.type) {
     case 'bigint':

package/plugins/data-exchange/index.js

@@ -33,6 +33,20 @@ function dataExchangePlugin(options = {}) {
     description: 'Admin spreadsheet import (CSV/XLSX) and Excel export',
     enabled,
 
+    register(ctx) {
+      if (!enabled) return;
+      const db = dbOption ?? ctx.db ?? ctx.app?.get?.('db') ?? null;
+      if (ctx.app && ctx.app.serviceRegistry) {
+        const { createExchangeServices } = require('../../src/services/builtins/exchange');
+        const exchangeServices = createExchangeServices({ db });
+        for (const [name, def] of Object.entries(exchangeServices)) {
+          if (!ctx.app.serviceRegistry.has(name)) {
+            ctx.app.serviceRegistry.register(name, def);
+          }
+        }
+      }
+    },
+
     onRoutesReady(ctx) {
       if (!enabled) return;
 

package/plugins/email/index.js

@@ -106,7 +106,20 @@ function emailPlugin(options = {}) {
     },
 
     register(ctx) {
-      // noop — templates loaded at plugin init; register available for future hot-reload
+      if (ctx.app && ctx.app.serviceRegistry) {
+        const { createMailServices } = require('../../src/services/builtins/mail');
+        const mailServices = createMailServices({
+          emailService,
+          registry,
+          db,
+          tableName,
+        });
+        for (const [name, def] of Object.entries(mailServices)) {
+          if (!ctx.app.serviceRegistry.has(name)) {
+            ctx.app.serviceRegistry.register(name, def);
+          }
+        }
+      }
     },
 
     onRoutesReady(ctx) {

package/plugins/index.js

@@ -25,6 +25,20 @@ const emailPlugin = require('./email');
 const contentPlugin = require('./content');
 const csrfPlugin = require('./csrf');
 const corsPlugin = require('./cors');
+const { basicAuthPlugin, createBasicAuthMiddleware } = require('./basic-auth');
+const {
+  realtimePlugin,
+  realtime,
+  createRealtime,
+  websocket,
+  createWebSocketAdapter,
+  sse,
+  createSseAdapter,
+  socketIo,
+  createSocketIoAdapter,
+  redis,
+  createRedisAdapter,
+} = require('./realtime');
 
 module.exports = {
   sitemapPlugin,
@@ -49,5 +63,20 @@ module.exports = {
   contentPlugin,
   csrfPlugin,
   corsPlugin,
+  basicAuthPlugin,
+  createBasicAuthMiddleware,
+  realtimePlugin,
+  realtime,
+  createRealtime,
+  websocket,
+  createWebSocketAdapter,
+  sse,
+  createSseAdapter,
+  socketIo,
+  createSocketIoAdapter,
+  redis,
+  createRedisAdapter,
+  queuePlugin: require('./queue'),
 };
 
+

package/plugins/queue/index.js

@@ -0,0 +1,108 @@
+/**
+ * Webspresso Background Job Queue Plugin
+ * @module plugins/queue
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const {
+  createQueueManager,
+  MemoryQueueAdapter,
+  DatabaseQueueAdapter,
+  RedisQueueAdapter,
+} = require('../../core/queue');
+
+/**
+ * @param {Object} [options]
+ * @param {'memory'|'database'|'redis'|Object} [options.adapter='memory'] - Queue backend adapter or name
+ * @param {Object} [options.db] - Knex/ORM database instance for database adapter
+ * @param {Object} [options.redisClient] - Redis client instance for redis adapter
+ * @param {string} [options.tableName='webspresso_jobs'] - Database queue table name
+ * @param {number} [options.concurrency=2] - Worker concurrency
+ * @param {number} [options.pollInterval=500] - Idle poll interval in ms
+ * @param {string} [options.jobsDir] - Path to jobs directory (defaults to <cwd>/jobs)
+ * @param {boolean} [options.autoStart=true] - Auto start processing
+ * @returns {Object} Plugin definition
+ */
+function queuePlugin(options = {}) {
+  const concurrency = options.concurrency || 2;
+  const pollInterval = options.pollInterval || 500;
+  const autoStart = options.autoStart !== false;
+  const jobsDir = options.jobsDir || path.join(process.cwd(), 'jobs');
+
+  let queueManager = null;
+
+  return {
+    name: 'queue',
+    version: '1.0.0',
+    description: 'Background Job Queue Engine with Memory, DB, and Redis adapters',
+
+    register(ctx) {
+      const { app, db } = ctx;
+
+      let adapter = options.adapter;
+
+      if (!adapter || adapter === 'memory') {
+        adapter = new MemoryQueueAdapter();
+      } else if (adapter === 'database' || adapter === 'db') {
+        const knexInstance = options.db?.knex || db?.knex || options.knex;
+        if (!knexInstance) {
+          throw new Error('[queuePlugin] Database queue adapter requires a valid database/knex instance.');
+        }
+        adapter = new DatabaseQueueAdapter({
+          knex: knexInstance,
+          tableName: options.tableName || 'webspresso_jobs',
+        });
+      } else if (adapter === 'redis') {
+        const client = options.redisClient || options.redis;
+        if (!client) {
+          throw new Error('[queuePlugin] Redis queue adapter requires a valid redisClient in options.');
+        }
+        adapter = new RedisQueueAdapter({
+          client,
+          prefix: options.prefix,
+        });
+      }
+
+      queueManager = createQueueManager({
+        adapter,
+        concurrency,
+        pollInterval,
+        jobsDir,
+        autoStart,
+      });
+
+      // Expose to ctx & app
+      ctx.queue = queueManager;
+      if (app) {
+        app.queue = queueManager;
+        app.set('webspresso.queue', queueManager);
+
+        // Attach req.queue middleware
+        app.use((req, res, next) => {
+          req.queue = queueManager;
+          next();
+        });
+      }
+
+      this.queue = queueManager;
+    },
+
+    onRoutesReady(ctx) {
+      if (jobsDir && fs.existsSync(jobsDir)) {
+        queueManager.loadJobsFromDirectory(jobsDir);
+      }
+    },
+
+    async dispose() {
+      if (queueManager) {
+        await queueManager.drain(5000);
+      }
+    },
+  };
+}
+
+module.exports = queuePlugin;
+module.exports.queuePlugin = queuePlugin;

package/plugins/realtime/index.js

@@ -0,0 +1,150 @@
+/**
+ * Webspresso Realtime Plugin
+ * Realtime plugin for Webspresso applications
+ * @module plugins/realtime
+ */
+
+const {
+  createRealtime,
+  RealtimeClient,
+  RealtimeSubscription,
+  SubscriptionRegistry,
+  createSubscriptionKey,
+  AuthManager,
+  ReconnectManager,
+  RealtimeError,
+  normalizeRealtimeError,
+  sanitizeErrorMessage,
+  EventEmitter,
+  DEFAULT_CAPABILITIES,
+
+  // Adapters
+  websocket,
+  createWebSocketAdapter,
+  WebSocketAdapter,
+  resolveWebSocketUrl,
+
+  sse,
+  createSseAdapter,
+  SseAdapter,
+  resolveSseUrl,
+
+  socketIo,
+  createSocketIoAdapter,
+  SocketIoAdapter,
+
+  redis,
+  createRedisAdapter,
+  RedisAdapter,
+} = require('../../core/realtime');
+
+/**
+ * Webspresso Realtime Plugin Factory
+ * 
+ * @param {Object} options
+ * @returns {Object} Webspresso plugin definition
+ */
+function realtimePlugin(options = {}) {
+  let clientInstance = null;
+
+  return {
+    name: 'realtime',
+    version: '1.0.0',
+    description: 'Framework-agnostic, plugin-based realtime layer for Webspresso',
+    _options: options,
+
+    api: {
+      getClient: () => clientInstance,
+    },
+
+    setup(app) {
+      if (!clientInstance) {
+        clientInstance = createRealtime(options);
+      }
+
+      if (app) {
+        app.realtime = clientInstance;
+      }
+
+      return () => {
+        if (clientInstance) {
+          clientInstance.destroy();
+        }
+      };
+    },
+
+    register(ctx) {
+      if (!clientInstance) {
+        clientInstance = createRealtime(options);
+      }
+
+      if (ctx.app) {
+        ctx.app.realtime = clientInstance;
+      }
+
+      if (typeof ctx.onDispose === 'function') {
+        ctx.onDispose(() => {
+          if (clientInstance) {
+            clientInstance.destroy();
+          }
+        });
+      }
+    },
+
+    browserReady(app) {
+      if (clientInstance) {
+        clientInstance.browserReady();
+      }
+    },
+
+    destroy(app) {
+      if (clientInstance) {
+        clientInstance.destroy();
+        clientInstance = null;
+      }
+    },
+  };
+}
+
+function realtime(options = {}) {
+  const client = createRealtime(options);
+  client.plugin = realtimePlugin(options);
+  return client;
+}
+
+module.exports = {
+  realtimePlugin,
+  realtime,
+  createRealtime,
+  RealtimeClient,
+  RealtimeSubscription,
+  SubscriptionRegistry,
+  createSubscriptionKey,
+  AuthManager,
+  ReconnectManager,
+  RealtimeError,
+  normalizeRealtimeError,
+  sanitizeErrorMessage,
+  EventEmitter,
+  DEFAULT_CAPABILITIES,
+
+  // Adapters
+  websocket,
+  createWebSocketAdapter,
+  WebSocketAdapter,
+  resolveWebSocketUrl,
+
+  sse,
+  createSseAdapter,
+  SseAdapter,
+  resolveSseUrl,
+
+  socketIo,
+  createSocketIoAdapter,
+  SocketIoAdapter,
+
+  redis,
+  createRedisAdapter,
+  RedisAdapter,
+};
+

package/plugins/recaptcha/index.js

@@ -107,6 +107,17 @@ function recaptchaPlugin(options = {}) {
     },
 
     register(ctx) {
+      if (ctx.middlewares) {
+        ctx.middlewares.recaptcha = (mwOpts = {}) =>
+          createRecaptchaMiddleware({
+            secret: resolveSecret(),
+            bodyField: mwOpts.bodyField,
+            version: mwOpts.version || version,
+            minScore: mwOpts.minScore ?? minScore,
+            expectedAction: mwOpts.expectedAction ?? expectedAction,
+          });
+      }
+
       ctx.addHelper('recaptchaScript', () =>
         version === 'v3' ? recaptchaScriptTag(siteKey) : recaptchaScriptTag()
       );