webspresso 0.0.103 → 0.0.105

package/core/limits/normalize.js

@@ -0,0 +1,222 @@
+'use strict';
+
+/**
+ * Webspresso Payload Limits Normalization & Utility
+ * Configures maximum body size limits and DoS protection for JSON, URL-encoded, raw, and text payloads.
+ *
+ * @module core/limits/normalize
+ */
+
+const DEFAULT_LIMITS = Object.freeze({
+  json: '1mb',
+  urlencoded: '1mb',
+  parameterLimit: 1000,
+  raw: false,
+  text: false,
+  captureRawBody: false,
+  exclude: Object.freeze([]),
+  routes: Object.freeze({}),
+});
+
+/**
+ * Parses byte size strings (e.g. '100kb', '5mb', '1gb') into integer bytes.
+ * If already a number or cannot be parsed, returns the value.
+ *
+ * @param {string|number} value
+ * @returns {number|string}
+ */
+function parseByteSize(value) {
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    return Math.max(0, Math.floor(value));
+  }
+  if (typeof value !== 'string') {
+    return value;
+  }
+
+  const trimmed = value.trim();
+  const match = /^([0-9]+(?:\.[0-9]+)?)\s*([a-zA-Z]+)?$/i.exec(trimmed);
+  if (!match) {
+    return value;
+  }
+
+  const num = parseFloat(match[1]);
+  const unit = (match[2] || 'b').toLowerCase();
+
+  const multipliers = {
+    b: 1,
+    byte: 1,
+    bytes: 1,
+    kb: 1024,
+    k: 1024,
+    kib: 1024,
+    mb: 1024 * 1024,
+    m: 1024 * 1024,
+    mib: 1024 * 1024,
+    gb: 1024 * 1024 * 1024,
+    g: 1024 * 1024 * 1024,
+    gib: 1024 * 1024 * 1024,
+    tb: 1024 * 1024 * 1024 * 1024,
+    t: 1024 * 1024 * 1024 * 1024,
+    tib: 1024 * 1024 * 1024 * 1024,
+  };
+
+  if (unit in multipliers) {
+    return Math.floor(num * multipliers[unit]);
+  }
+
+  return value;
+}
+
+/**
+ * Normalizes user limits options into a structured, validated configuration.
+ *
+ * @param {Object|string|number} [options]
+ * @returns {Object} Normalized limits configuration
+ */
+function normalizeLimits(options = {}) {
+  // If options is top-level createApp options, unwrap options.limits ?? options.server?.limits
+  let raw = options;
+  if (options && typeof options === 'object') {
+    if ('limits' in options || (options.server && 'limits' in options.server)) {
+      raw = options.limits ?? options.server?.limits ?? {};
+    }
+  }
+
+  // Shorthand string or number: e.g. limits: '5mb' or limits: 5242880
+  if (typeof raw === 'string' || typeof raw === 'number') {
+    const size = parseByteSize(raw);
+    return {
+      json: { enabled: true, limit: size, strict: true, options: {} },
+      urlencoded: { enabled: true, limit: size, extended: true, parameterLimit: 1000, options: {} },
+      raw: { enabled: false, limit: size, type: 'application/octet-stream', options: {} },
+      text: { enabled: false, limit: size, type: 'text/plain', options: {} },
+      parameterLimit: 1000,
+      captureRawBody: false,
+      exclude: [],
+      routes: {},
+    };
+  }
+
+  const opts = (raw && typeof raw === 'object') ? raw : {};
+
+  // Global parameterLimit fallback
+  const globalParamLimit = typeof opts.parameterLimit === 'number'
+    ? Math.max(1, Math.floor(opts.parameterLimit))
+    : 1000;
+
+  // 1. JSON
+  let json = { enabled: true, limit: parseByteSize('1mb'), strict: true, options: {} };
+  if (opts.json === false) {
+    json.enabled = false;
+  } else if (typeof opts.json === 'string' || typeof opts.json === 'number') {
+    json.limit = parseByteSize(opts.json);
+  } else if (opts.json && typeof opts.json === 'object') {
+    const { limit, strict, verify, enabled, ...rest } = opts.json;
+    json = {
+      enabled: enabled !== false,
+      limit: limit !== undefined ? parseByteSize(limit) : parseByteSize('1mb'),
+      strict: strict !== false,
+      verify: typeof verify === 'function' ? verify : undefined,
+      options: rest,
+    };
+  }
+
+  // 2. URL-encoded
+  let urlencoded = { enabled: true, limit: parseByteSize('1mb'), extended: true, parameterLimit: globalParamLimit, options: {} };
+  if (opts.urlencoded === false) {
+    urlencoded.enabled = false;
+  } else if (typeof opts.urlencoded === 'string' || typeof opts.urlencoded === 'number') {
+    urlencoded.limit = parseByteSize(opts.urlencoded);
+  } else if (opts.urlencoded && typeof opts.urlencoded === 'object') {
+    const { limit, extended, parameterLimit, verify, enabled, ...rest } = opts.urlencoded;
+    urlencoded = {
+      enabled: enabled !== false,
+      limit: limit !== undefined ? parseByteSize(limit) : parseByteSize('1mb'),
+      extended: extended !== false,
+      parameterLimit: typeof parameterLimit === 'number' ? Math.max(1, Math.floor(parameterLimit)) : globalParamLimit,
+      verify: typeof verify === 'function' ? verify : undefined,
+      options: rest,
+    };
+  }
+
+  // 3. Raw Body (application/octet-stream by default)
+  let rawBody = { enabled: false, limit: parseByteSize('1mb'), type: 'application/octet-stream', options: {} };
+  if (opts.raw === true) {
+    rawBody.enabled = true;
+    rawBody.limit = parseByteSize('1mb');
+  } else if (typeof opts.raw === 'string' || typeof opts.raw === 'number') {
+    rawBody.enabled = true;
+    rawBody.limit = parseByteSize(opts.raw);
+  } else if (opts.raw && typeof opts.raw === 'object') {
+    const { limit, type, verify, enabled, ...rest } = opts.raw;
+    rawBody = {
+      enabled: enabled !== false,
+      limit: limit !== undefined ? parseByteSize(limit) : parseByteSize('1mb'),
+      type: type || 'application/octet-stream',
+      verify: typeof verify === 'function' ? verify : undefined,
+      options: rest,
+    };
+  }
+
+  // 4. Text Body (text/plain by default)
+  let textBody = { enabled: false, limit: parseByteSize('1mb'), type: 'text/plain', options: {} };
+  if (opts.text === true) {
+    textBody.enabled = true;
+    textBody.limit = parseByteSize('1mb');
+  } else if (typeof opts.text === 'string' || typeof opts.text === 'number') {
+    textBody.enabled = true;
+    textBody.limit = parseByteSize(opts.text);
+  } else if (opts.text && typeof opts.text === 'object') {
+    const { limit, type, verify, enabled, ...rest } = opts.text;
+    textBody = {
+      enabled: enabled !== false,
+      limit: limit !== undefined ? parseByteSize(limit) : parseByteSize('1mb'),
+      type: type || 'text/plain',
+      verify: typeof verify === 'function' ? verify : undefined,
+      options: rest,
+    };
+  }
+
+  // 5. Raw Body Capture setting
+  const captureRawBody = opts.captureRawBody !== undefined ? opts.captureRawBody : false;
+
+  // 6. Exclusions
+  const exclude = Array.isArray(opts.exclude) ? opts.exclude.slice() : [];
+
+  // 7. Route overrides
+  const routes = {};
+  if (opts.routes && typeof opts.routes === 'object') {
+    for (const [pattern, routeConfig] of Object.entries(opts.routes)) {
+      if (routeConfig === false) {
+        routes[pattern] = false;
+      } else if (typeof routeConfig === 'string' || typeof routeConfig === 'number') {
+        const size = parseByteSize(routeConfig);
+        routes[pattern] = {
+          json: { enabled: true, limit: size, strict: true, options: {} },
+          urlencoded: { enabled: true, limit: size, extended: true, parameterLimit: globalParamLimit, options: {} },
+          raw: { enabled: false, limit: size, type: 'application/octet-stream', options: {} },
+          text: { enabled: false, limit: size, type: 'text/plain', options: {} },
+        };
+      } else if (routeConfig && typeof routeConfig === 'object') {
+        routes[pattern] = normalizeLimits(routeConfig);
+      }
+    }
+  }
+
+  return {
+    json,
+    urlencoded,
+    raw: rawBody,
+    text: textBody,
+    parameterLimit: globalParamLimit,
+    captureRawBody,
+    exclude,
+    routes,
+  };
+}
+
+module.exports = {
+  DEFAULT_LIMITS,
+  parseByteSize,
+  normalizeLimits,
+};

package/core/orm/batch.js

@@ -0,0 +1,70 @@
+'use strict';
+
+/**
+ * Webspresso ORM - Batch & Bulk Operation Utilities
+ * Manages SQL parameter variable limit protection, auto-chunking, and bulk operations.
+ *
+ * @module core/orm/batch
+ */
+
+/**
+ * Calculates a safe chunk size based on dialect and column count to prevent
+ * SQLITE_ERROR: too many SQL variables or max query length packet issues.
+ *
+ * @param {import('knex').Knex|Object} knexInstance - Knex or transaction instance
+ * @param {number} columnCount - Number of columns per inserted row
+ * @param {number} [requestedChunkSize] - User-specified chunk size
+ * @returns {number} Safe chunk size
+ */
+function calculateSafeChunkSize(knexInstance, columnCount = 10, requestedChunkSize = null) {
+  const cols = Math.max(1, columnCount || 10);
+  const clientName = (
+    knexInstance?.client?.dialect ||
+    knexInstance?.client?.config?.client ||
+    ''
+  ).toLowerCase();
+  const isSqlite = clientName.includes('sqlite');
+
+  // SQLite variable limits:
+  // Legacy SQLite: 999
+  // Modern SQLite (>= 3.32.0): 32,766
+  // We use 990 as a conservative threshold for maximum compatibility across any SQLite build.
+  const safeParamLimit = isSqlite ? 990 : 10000;
+  const maxRowsByParamLimit = Math.max(1, Math.floor(safeParamLimit / cols));
+
+  if (typeof requestedChunkSize === 'number' && requestedChunkSize > 0) {
+    if (isSqlite) {
+      // Ensure requested chunk size doesn't exceed SQLite variable limit
+      return Math.min(requestedChunkSize, maxRowsByParamLimit);
+    }
+    return requestedChunkSize;
+  }
+
+  // Default optimal chunk sizes
+  if (isSqlite) {
+    return Math.min(500, maxRowsByParamLimit);
+  }
+  return 1000;
+}
+
+/**
+ * Splits an array into sub-arrays of specified chunk size
+ * @template T
+ * @param {T[]} array - Source array
+ * @param {number} size - Chunk size
+ * @returns {T[][]}
+ */
+function chunkArray(array, size) {
+  if (!Array.isArray(array) || array.length === 0) return [];
+  const chunkSize = Math.max(1, Math.floor(size || 500));
+  const chunks = [];
+  for (let i = 0; i < array.length; i += chunkSize) {
+    chunks.push(array.slice(i, i + chunkSize));
+  }
+  return chunks;
+}
+
+module.exports = {
+  calculateSafeChunkSize,
+  chunkArray,
+};

package/core/orm/cache/fingerprint.js

@@ -3,7 +3,7 @@
  * @module core/orm/cache/fingerprint
  */
 
-const crypto = require('crypto');
+const { sha256 } = require('../../utils/crypto');
 
 /**
  * @param {*} v
@@ -94,7 +94,7 @@ function hashKey(model, scopeContext, parts) {
     ...parts,
   });
   const json = JSON.stringify(payload);
-  return crypto.createHash('sha256').update(json).digest('hex').slice(0, 40);
+  return sha256(json).slice(0, 40);
 }
 
 module.exports = {

package/core/orm/cache/memory-provider.js

@@ -1,12 +1,18 @@
 /**
- * In-memory CacheProvider (process-local, tag-based invalidation)
+ * In-memory CacheProvider (process-local, tag-based invalidation, true LRU & memory budget)
+ * Upgraded with zero-allocation O(1) LRU eviction, byte budget constraints, and leak-free tag sets.
  * @module core/orm/cache/memory-provider
  */
 
+const { createTaggedLruCache } = require('../../cache');
+
 /**
  * @typedef {Object} MemoryCacheProviderOptions
- * @property {number} [maxEntries=10000] - Max stored keys; FIFO evict on overflow
- * @property {number} [defaultTtlMs=0] - Default TTL (0 = no expiry)
+ * @property {number} [maxEntries=10000] - Max stored keys; LRU evict on overflow
+ * @property {number} [maxBytes=0] - Max byte size budget (0 = disabled)
+ * @property {number} [maxMemoryMb=0] - Max megabytes budget (converts to bytes)
+ * @property {number} [defaultTtlMs=0] - Default TTL in ms (0 = no expiry)
+ * @property {function(*, string): number} [sizeCalculation] - Custom byte sizer
  */
 
 /**
@@ -16,116 +22,27 @@
 function createMemoryCacheProvider(options = {}) {
   const maxEntries = options.maxEntries ?? 10000;
   const defaultTtlMs = options.defaultTtlMs ?? 0;
+  const maxBytes = options.maxBytes ?? (options.maxMemoryMb ? options.maxMemoryMb * 1024 * 1024 : 0);
 
-  /** @type {Map<string, { value: *, expiresAt: number, tags: Set<string> }>} */
-  const store = new Map();
-  /** @type {Map<string, Set<string>>} */
-  const tagToKeys = new Map();
-  /** @type {Map<string, Set<string>>} */
-  const keyToTags = new Map();
-
-  function removeKey(key) {
-    const tags = keyToTags.get(key);
-    if (tags) {
-      for (const t of tags) {
-        const set = tagToKeys.get(t);
-        if (set) {
-          set.delete(key);
-          if (set.size === 0) tagToKeys.delete(t);
-        }
-      }
-    }
-    keyToTags.delete(key);
-    store.delete(key);
-  }
-
-  function get(key) {
-    const entry = store.get(key);
-    if (!entry) return undefined;
-    if (entry.expiresAt > 0 && Date.now() > entry.expiresAt) {
-      removeKey(key);
-      return undefined;
-    }
-    return entry.value;
-  }
-
-  function set(key, value, opts = {}) {
-    const tags = Array.isArray(opts.tags) ? opts.tags : [];
-    const ttlMs = opts.ttlMs ?? defaultTtlMs;
-
-    if (store.has(key)) removeKey(key);
-
-    if (maxEntries > 0 && store.size >= maxEntries) {
-      // Active sweep: evict expired entries before falling back to FIFO eviction
-      const now = Date.now();
-      let freed = 0;
-      for (const [k, entry] of store.entries()) {
-        if (entry.expiresAt > 0 && now > entry.expiresAt) {
-          removeKey(k);
-          freed++;
-          if (freed >= 10 || store.size < maxEntries) break;
-        }
-      }
-      if (store.size >= maxEntries) {
-        const first = store.keys().next().value;
-        if (first !== undefined) removeKey(first);
-      }
-    }
-
-    const expiresAt = ttlMs > 0 ? Date.now() + ttlMs : 0;
-    const tagSet = new Set(tags);
-    store.set(key, { value, expiresAt, tags: tagSet });
-    keyToTags.set(key, new Set(tags));
-
-    for (const t of tags) {
-      if (!tagToKeys.has(t)) tagToKeys.set(t, new Set());
-      tagToKeys.get(t).add(key);
-    }
-  }
-
-  function invalidateTags(tags) {
-    const toDelete = new Set();
-    for (const t of tags) {
-      const keys = tagToKeys.get(t);
-      if (!keys) continue;
-      for (const k of keys) toDelete.add(k);
-    }
-    for (const k of toDelete) removeKey(k);
-    for (const t of tags) tagToKeys.delete(t);
-  }
-
-  function pruneExpired() {
-    const now = Date.now();
-    let count = 0;
-    for (const [k, entry] of store.entries()) {
-      if (entry.expiresAt > 0 && now > entry.expiresAt) {
-        removeKey(k);
-        count++;
-      }
-    }
-    return count;
-  }
-
-  function clear() {
-    store.clear();
-    tagToKeys.clear();
-    keyToTags.clear();
-  }
-
-  function getSizeStats() {
-    return {
-      entries: store.size,
-      tags: tagToKeys.size,
-    };
-  }
+  const cache = createTaggedLruCache({
+    maxEntries,
+    defaultTtl: defaultTtlMs,
+    maxBytes,
+    sizeCalculation: options.sizeCalculation,
+  });
 
   return {
-    get,
-    set,
-    invalidateTags,
-    pruneExpired,
-    clear,
-    getSizeStats,
+    get: (key) => cache.get(key),
+    set: (key, value, opts = {}) => cache.set(key, value, {
+      tags: opts.tags,
+      ttlMs: opts.ttlMs ?? defaultTtlMs,
+      size: opts.size,
+    }),
+    invalidateTags: (tags) => cache.invalidateTags(tags),
+    pruneExpired: () => cache.pruneExpired(),
+    clear: () => cache.clear(),
+    getSizeStats: () => cache.getSizeStats(),
+    getStats: () => cache.getStats(),
   };
 }
 

package/core/orm/index.js

@@ -112,9 +112,12 @@ function createDatabase(config) {
   }
 
   let knexInstance;
-  try {
-    knexInstance = knex(knexConfig);
-  } catch (e) {
+  if (config.knex) {
+    knexInstance = config.knex;
+  } else {
+    try {
+      knexInstance = knex(knexConfig);
+    } catch (e) {
     // Provide helpful error message
     if (e.message && (e.message.includes('Cannot find module') || e.message.includes('npm install'))) {
       const driverName = driverMap[config.client] || config.client;
@@ -133,6 +136,7 @@ function createDatabase(config) {
     }
     throw e;
   }
+}
 
   // Create migration manager
   const migrationConfig = config.migrations || {};
@@ -284,24 +288,32 @@ function createDatabase(config) {
     const runner = (ambientTrx && typeof ambientTrx.transaction === 'function') ? ambientTrx : knexInstance;
 
     return runner.transaction(async (trx) => {
+      let currentScope = scopeContext ? { ...scopeContext } : createScopeContext();
       const trxContext = {
         trx,
         getRepository(modelName, sContext) {
           const model = getModelInstance(modelName);
-          const ctx = sContext || scopeContext || createScopeContext();
+          const ctx = sContext || currentScope;
           return createRepository(model, trx, ctx, ormCacheLayer);
         },
         createRepository(model, sContext) {
-          const ctx = sContext || scopeContext || createScopeContext();
+          const ctx = sContext || currentScope;
           return createRepository(model, trx, ctx, ormCacheLayer);
         },
         forTenant(tenantId) {
-          if (!scopeContext) scopeContext = createScopeContext();
-          scopeContext.tenantId = tenantId;
+          currentScope = { ...currentScope, tenantId };
+          return this;
+        },
+        forUser(user) {
+          currentScope = { ...currentScope, user };
+          return this;
+        },
+        withoutRls() {
+          currentScope = { ...currentScope, rlsDisabled: true };
           return this;
         },
         getScopeContext() {
-          return { ...(scopeContext || createScopeContext()) };
+          return { ...currentScope };
         },
       };
       return runWithAmbientTransaction(trx, () => callback(trxContext));
@@ -318,6 +330,45 @@ function createDatabase(config) {
     getRepository,
     createRepository: createRepositoryFromModel,
     query,
+    forUser(user) {
+      return {
+        getRepository(modelName, customContext = {}) {
+          return getRepository(modelName, { ...customContext, user });
+        },
+        createRepository(model, customContext = {}) {
+          return createRepositoryFromModel(model, { ...customContext, user });
+        },
+        query(modelName, customContext = {}) {
+          return query(modelName, { ...customContext, user });
+        },
+      };
+    },
+    withoutRls() {
+      return {
+        getRepository(modelName, customContext = {}) {
+          return getRepository(modelName, { ...customContext, rlsDisabled: true });
+        },
+        createRepository(model, customContext = {}) {
+          return createRepositoryFromModel(model, { ...customContext, rlsDisabled: true });
+        },
+        query(modelName, customContext = {}) {
+          return query(modelName, { ...customContext, rlsDisabled: true });
+        },
+      };
+    },
+    forTenant(tenantId) {
+      return {
+        getRepository(modelName, customContext = {}) {
+          return getRepository(modelName, { ...customContext, tenantId });
+        },
+        createRepository(model, customContext = {}) {
+          return createRepositoryFromModel(model, { ...customContext, tenantId });
+        },
+        query(modelName, customContext = {}) {
+          return query(modelName, { ...customContext, tenantId });
+        },
+      };
+    },
     transaction,
     runInTransaction: transaction,
     getAmbientTransaction,
@@ -392,4 +443,21 @@ module.exports = {
   // Schema Diff & Makemigrations (Django-inspired)
   diffSchema: require('./migrations/diff').diffSchema,
   makeMigrations: require('./migrations/diff').makeMigrations,
+  // Universal Query Filters (REST Resources & Admin Panel)
+  buildFilteredQuery: require('./query-filters').buildFilteredQuery,
+  applyColumnFilters: require('./query-filters').applyColumnFilters,
+  applyFilterCondition: require('./query-filters').applyFilterCondition,
+  queryFilters: require('./query-filters'),
+  // Batch & Bulk Operation Utilities
+  calculateSafeChunkSize: require('./batch').calculateSafeChunkSize,
+  chunkArray: require('./batch').chunkArray,
+  // Row Level Security (RLS) & Scopes
+  applyRlsScope: require('./scopes').applyRlsScope,
+  applyScopes: require('./scopes').applyScopes,
+  applyInsertRls: require('./scopes').applyInsertRls,
+  checkUpdateRls: require('./scopes').checkUpdateRls,
+  isRlsBypassed: require('./scopes').isRlsBypassed,
+  getUserId: require('./scopes').getUserId,
+  getTenantId: require('./scopes').getTenantId,
+  createScopeContext: require('./scopes').createScopeContext,
 };

package/core/orm/json-fields.js

@@ -3,6 +3,8 @@
  * @module core/orm/json-fields
  */
 
+const { safeJsonParse } = require('../utils/json');
+
 /**
  * Get JSON column names from model
  * @param {import('./types').ModelDefinition} model - Model definition
@@ -15,7 +17,25 @@ function getJsonColumns(model) {
   const jsonCols = new Set();
   if (model && model.columns) {
     for (const [name, meta] of model.columns) {
-      if (meta.type === 'json' || meta.type === 'array' || meta.type === 'files') {
+      if (meta && (meta.type === 'json' || meta.type === 'array' || meta.type === 'files')) {
+        jsonCols.add(name);
+      }
+    }
+  }
+  if (model && model.schema && model.schema.shape) {
+    for (const [name, fieldSchema] of Object.entries(model.schema.shape)) {
+      let current = fieldSchema;
+      while (current && current._def) {
+        if (current._def.innerType) {
+          current = current._def.innerType;
+        } else if (current._def.schema) {
+          current = current._def.schema;
+        } else {
+          break;
+        }
+      }
+      const typeName = current?._def?.typeName;
+      if (typeName === 'ZodRecord' || typeName === 'ZodObject' || typeName === 'ZodArray') {
         jsonCols.add(name);
       }
     }
@@ -57,13 +77,7 @@ function deserializeJsonFields(record, jsonColumns) {
 
   for (const col of jsonColumns) {
     if (col in record && record[col] !== null && record[col] !== undefined) {
-      if (typeof record[col] === 'string') {
-        try {
-          record[col] = JSON.parse(record[col]);
-        } catch {
-          // If parsing fails, keep the original string value
-        }
-      }
+      record[col] = safeJsonParse(record[col], record[col]);
     }
   }
   return record;

package/core/orm/model.js

@@ -39,6 +39,7 @@ function defineModel(options) {
     timestamps: timestampsOpt,
     softDelete: softDeleteOpt,
     softDeletes: softDeletesOpt,
+    rls: rlsOpt,
     options: nestedOptions = {},
   } = options;
 
@@ -185,6 +186,13 @@ function defineModel(options) {
     };
   }
 
+  const rlsConfig = rlsOpt !== undefined
+    ? rlsOpt
+    : (nestedOptions.rls !== undefined ? nestedOptions.rls : scopes.rls);
+  const normalizedRls = (typeof rlsConfig === 'function' || (rlsConfig && typeof rlsConfig === 'object'))
+    ? rlsConfig
+    : null;
+
   // Create model definition
   const model = {
     name,
@@ -198,9 +206,11 @@ function defineModel(options) {
       timestamps: Boolean(timestampsConfig),
       tenant: scopes.tenant || null,
     },
+    rls: normalizedRls,
     options: {
       timestamps: timestampsConfig || false,
       softDelete: softDeleteConfig || false,
+      rls: normalizedRls,
       ...nestedOptions,
     },
     columns,