@yunsoft/yuncms-core 0.1.3 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yunsoft/yuncms-core",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Core services, schema, authentication, permissions and storage primitives for YunCMS.",
   "license": "MIT",
   "type": "module",

package/src/bootstrap.js

@@ -10,6 +10,8 @@ import { systemPermissionResourcesMigration } from './migrations/0007-system-per
 import { studioLogoFileMigration } from './migrations/0008-studio-logo-file.js';
 import { schemaDisplayNamesMigration } from './migrations/0009-schema-display-names.js';
 import { studioFaviconFileMigration } from './migrations/0010-studio-favicon-file.js';
+import { rolePermissionActionsMigration } from './migrations/0011-role-permission-actions.js';
+import { filesReadFiltersMigration } from './migrations/0012-files-read-filters.js';
 import { readSchemaVersion } from './schema-version.js';
 import { ensurePublicRole } from './setup.js';
 
@@ -24,6 +26,8 @@ export const CORE_MIGRATIONS = Object.freeze([
   studioLogoFileMigration,
   schemaDisplayNamesMigration,
   studioFaviconFileMigration,
+  rolePermissionActionsMigration,
+  filesReadFiltersMigration,
 ]);
 
 export const REQUIRED_CORE_MIGRATION_IDS = Object.freeze(

package/src/cache.js

@@ -0,0 +1,85 @@
+function cacheError(message) {
+  const error = new Error(message);
+  error.code = 'INVALID_CACHE_CONFIG';
+  return error;
+}
+
+export function isCacheStore(store) {
+  return Boolean(
+    store
+    && typeof store.get === 'function'
+    && typeof store.set === 'function'
+    && typeof store.delete === 'function'
+    && typeof store.clear === 'function',
+  );
+}
+
+export class MemoryCacheStore {
+  constructor({
+    ttlMs = 30_000,
+    maxEntries = 5_000,
+    now = () => Date.now(),
+  } = {}) {
+    if (!Number.isInteger(ttlMs) || ttlMs < 1) throw cacheError('Cache ttlMs must be a positive integer');
+    if (!Number.isInteger(maxEntries) || maxEntries < 1) {
+      throw cacheError('Cache maxEntries must be a positive integer');
+    }
+    if (typeof now !== 'function') throw cacheError('Cache now must be a function');
+
+    this.ttlMs = ttlMs;
+    this.maxEntries = maxEntries;
+    this.now = now;
+    this.entries = new Map();
+  }
+
+  #deleteExpired(timestamp) {
+    for (const [key, entry] of this.entries) {
+      if (entry.expiresAt <= timestamp) this.entries.delete(key);
+    }
+  }
+
+  #ensureCapacity(timestamp, incomingKey) {
+    this.#deleteExpired(timestamp);
+    if (this.entries.has(incomingKey)) return;
+    while (this.entries.size >= this.maxEntries) {
+      const oldestKey = this.entries.keys().next().value;
+      if (oldestKey === undefined) break;
+      this.entries.delete(oldestKey);
+    }
+  }
+
+  async get(key) {
+    const entry = this.entries.get(String(key));
+    if (!entry) return undefined;
+    if (entry.expiresAt <= this.now()) {
+      this.entries.delete(String(key));
+      return undefined;
+    }
+    return entry.value;
+  }
+
+  async set(key, value, { ttlMs = this.ttlMs } = {}) {
+    if (!Number.isInteger(ttlMs) || ttlMs < 1) throw cacheError('Cache entry ttlMs must be a positive integer');
+    const normalizedKey = String(key);
+    const timestamp = this.now();
+    this.#ensureCapacity(timestamp, normalizedKey);
+    this.entries.delete(normalizedKey);
+    this.entries.set(normalizedKey, {
+      value,
+      expiresAt: timestamp + ttlMs,
+    });
+    return value;
+  }
+
+  async delete(key) {
+    return this.entries.delete(String(key));
+  }
+
+  async clear() {
+    this.entries.clear();
+  }
+
+  get size() {
+    return this.entries.size;
+  }
+}

package/src/config.js

@@ -24,6 +24,14 @@ function readString(value, fallback = '') {
   return value === undefined ? fallback : String(value);
 }
 
+function readCacheStore(value) {
+  const store = readString(value, 'memory').trim().toLowerCase();
+  if (store !== 'memory') {
+    throw new Error(`CACHE_STORE must be memory until a shared-store adapter is configured, received: ${store}`);
+  }
+  return store;
+}
+
 export function loadEnvFileIfPresent(path = '.env') {
   try {
     loadEnvFile(path);
@@ -44,10 +52,52 @@ export function loadConfig(env = process.env) {
       port: serverPort,
       studioOrigin,
       trustProxyHops: readInteger(env.TRUST_PROXY_HOPS, 0, 'TRUST_PROXY_HOPS', { min: 0, max: 10 }),
+      rateLimit: {
+        enabled: readBoolean(env.API_RATE_LIMIT_ENABLED, true),
+        windowMs: readInteger(env.API_RATE_LIMIT_WINDOW_MS, 60_000, 'API_RATE_LIMIT_WINDOW_MS', {
+          min: 1000,
+          max: 24 * 60 * 60 * 1000,
+        }),
+        max: readInteger(env.API_RATE_LIMIT_MAX, 300, 'API_RATE_LIMIT_MAX', {
+          min: 1,
+          max: 1_000_000,
+        }),
+        maxBuckets: readInteger(env.API_RATE_LIMIT_MAX_BUCKETS, 10_000, 'API_RATE_LIMIT_MAX_BUCKETS', {
+          min: 1,
+          max: 1_000_000,
+        }),
+      },
+      pressure: {
+        enabled: readBoolean(env.PRESSURE_LIMIT_ENABLED, true),
+        maxConcurrent: readInteger(env.PRESSURE_MAX_CONCURRENT, 250, 'PRESSURE_MAX_CONCURRENT', {
+          min: 1,
+          max: 100_000,
+        }),
+        maxHeapPercent: readInteger(env.PRESSURE_MAX_HEAP_PERCENT, 95, 'PRESSURE_MAX_HEAP_PERCENT', {
+          min: 1,
+          max: 100,
+        }),
+        retryAfterSeconds: readInteger(env.PRESSURE_RETRY_AFTER_SECONDS, 1, 'PRESSURE_RETRY_AFTER_SECONDS', {
+          min: 1,
+          max: 3600,
+        }),
+      },
     },
     logging: {
       level: readString(env.LOG_LEVEL, 'info'),
     },
+    cache: {
+      enabled: readBoolean(env.CACHE_ENABLED, true),
+      store: readCacheStore(env.CACHE_STORE),
+      ttlMs: readInteger(env.CACHE_TTL_MS, 30_000, 'CACHE_TTL_MS', {
+        min: 1,
+        max: 24 * 60 * 60 * 1000,
+      }),
+      maxEntries: readInteger(env.CACHE_MAX_ENTRIES, 5_000, 'CACHE_MAX_ENTRIES', {
+        min: 1,
+        max: 1_000_000,
+      }),
+    },
     database: {
       host: readString(env.DB_HOST, '127.0.0.1'),
       port: readInteger(env.DB_PORT, 3306, 'DB_PORT', { min: 1, max: 65535 }),

package/src/context.js

@@ -1,4 +1,5 @@
 import { requireAccountability } from './accountability.js';
+import { isCacheStore } from './cache.js';
 
 export function createRequestContext({
   accountability,
@@ -9,14 +10,16 @@ export function createRequestContext({
   env = {},
   emitter = null,
   storage = null,
-  permissionCache = new Map(),
+  permissionCache = null,
   requestId = null,
 } = {}) {
   requireAccountability(accountability);
 
   if (!services) throw new Error('Service registry is required');
   if (!database) throw new Error('Database handle is required');
-  if (!(permissionCache instanceof Map)) throw new Error('Permission cache must be a Map');
+  if (permissionCache !== null && !isCacheStore(permissionCache)) {
+    throw new Error('Permission cache must implement the cache-store contract');
+  }
 
   return Object.freeze({
     accountability,

package/src/index.js

@@ -1,10 +1,17 @@
 export { DEFAULT_SERVER_PORT, loadConfig, loadEnvFileIfPresent } from './config.js';
+export { isCacheStore, MemoryCacheStore } from './cache.js';
 export { createDatabasePool, pingDatabase, closeDatabasePool } from './database.js';
 export { withTransaction, withConnectionTransaction } from './transaction.js';
 export { assertIdentifier, quoteIdentifier } from './identifier.js';
 export { normalizeDisplayName, normalizeSchemaKey, resolveSchemaName } from './schema-key.js';
 export { YunCmsDatabaseError, normalizeDatabaseError, isRetryableDatabaseError } from './errors.js';
 export { withDatabaseRetry } from './retry.js';
+export {
+  MAINTENANCE_BYPASS_ENV,
+  maintenanceLockPath,
+  hashMaintenanceBypassToken,
+  assertMaintenanceStartupAllowed,
+} from './maintenance-state.js';
 export {
   createAccountability,
   createPublicAccountability,
@@ -63,6 +70,7 @@ export {
 } from './system-fields.js';
 export {
   assertActionOnlyPermissionPayload,
+  assertSystemPermissionPayload,
   assertSystemResourceAction,
   isPermissionManagedSystemResource,
   systemPermissionConfig,
@@ -77,6 +85,7 @@ export { withAdvisoryLock } from './advisory-lock.js';
 export {
   ensureMigrationJournal,
   readAppliedMigrations,
+  readMigrationAttempts,
   validateMigration,
   applyMigrations,
   assertMigrationsApplied,

package/src/maintenance-state.js

@@ -0,0 +1,89 @@
+import { createHash, timingSafeEqual } from 'node:crypto';
+import { realpathSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+export const MAINTENANCE_BYPASS_ENV = 'YUNCMS_MAINTENANCE_BYPASS_TOKEN';
+
+function sha256(value) {
+  return createHash('sha256').update(String(value)).digest('hex');
+}
+
+export function canonicalProjectPath(cwd = process.cwd()) {
+  const absolute = resolve(cwd);
+  try {
+    return realpathSync.native ? realpathSync.native(absolute) : realpathSync(absolute);
+  } catch {
+    return absolute;
+  }
+}
+
+export function maintenanceLockPath(cwd = process.cwd()) {
+  const projectKey = sha256(canonicalProjectPath(cwd)).slice(0, 32);
+  return join(tmpdir(), 'yuncms-update-locks', `${projectKey}.lock`);
+}
+
+export function hashMaintenanceBypassToken(token) {
+  if (typeof token !== 'string' || token.length < 32) {
+    const error = new Error('Maintenance bypass token must contain at least 32 characters');
+    error.code = 'MAINTENANCE_BYPASS_TOKEN_INVALID';
+    throw error;
+  }
+  return sha256(token);
+}
+
+function hashesEqual(left, right) {
+  if (typeof left !== 'string' || typeof right !== 'string') return false;
+  if (!/^[0-9a-f]{64}$/i.test(left) || !/^[0-9a-f]{64}$/i.test(right)) return false;
+  const leftBuffer = Buffer.from(left, 'hex');
+  const rightBuffer = Buffer.from(right, 'hex');
+  return leftBuffer.length === rightBuffer.length && timingSafeEqual(leftBuffer, rightBuffer);
+}
+
+async function readMaintenanceState(path, readFileFn) {
+  let text;
+  try {
+    text = await readFileFn(path, 'utf8');
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null;
+    throw error;
+  }
+
+  try {
+    const state = JSON.parse(text);
+    if (!state || typeof state !== 'object' || Array.isArray(state)) throw new Error('invalid state');
+    return state;
+  } catch (cause) {
+    const error = new Error(`YunCMS maintenance lock is unreadable or invalid: ${path}`);
+    error.code = 'YUNCMS_MAINTENANCE_ACTIVE';
+    error.lockPath = path;
+    error.cause = cause;
+    throw error;
+  }
+}
+
+export async function assertMaintenanceStartupAllowed({
+  cwd = process.cwd(),
+  env = process.env,
+  readFileFn = readFile,
+} = {}) {
+  const path = maintenanceLockPath(cwd);
+  const state = await readMaintenanceState(path, readFileFn);
+  if (!state) return true;
+
+  const suppliedToken = env?.[MAINTENANCE_BYPASS_ENV];
+  if (typeof suppliedToken === 'string' && suppliedToken.length >= 32) {
+    const suppliedHash = sha256(suppliedToken);
+    if (hashesEqual(suppliedHash, state.bypassTokenHash)) return true;
+  }
+
+  const error = new Error(
+    `YunCMS maintenance is active for this project. Do not start the application until the maintenance operation finishes: ${path}`,
+  );
+  error.code = 'YUNCMS_MAINTENANCE_ACTIVE';
+  error.lockPath = path;
+  error.startedAt = typeof state.startedAt === 'string' ? state.startedAt : null;
+  error.pid = Number.isInteger(state.pid) ? state.pid : null;
+  throw error;
+}

package/src/migrations/0011-role-permission-actions.js

@@ -0,0 +1,15 @@
+export const rolePermissionActionsMigration = {
+  id: '0011-role-permission-actions',
+  statements: [
+    `UPDATE yuncms_collections
+     SET metadata = JSON_SET(
+       COALESCE(metadata, JSON_OBJECT()),
+       '$.permissionManaged', TRUE,
+       '$.permissionMode', 'action-only',
+       '$.resource', 'roles',
+       '$.allowedActions', JSON_ARRAY('read', 'create', 'update', 'delete')
+     )
+     WHERE collection = 'yuncms_roles' AND \`system\` = 1`,
+    `UPDATE yuncms_schema_state SET version = version + 1 WHERE id = 1`,
+  ],
+};

package/src/migrations/0012-files-read-filters.js

@@ -0,0 +1,14 @@
+export const filesReadFiltersMigration = {
+  id: '0012-files-read-filters',
+  statements: [
+    `UPDATE yuncms_collections
+     SET metadata = JSON_SET(
+       COALESCE(metadata, JSON_OBJECT()),
+       '$.permissionMode',
+       'filter-read'
+     )
+     WHERE collection = 'yuncms_files'
+       AND \`system\` = 1`,
+    `UPDATE yuncms_schema_state SET version = version + 1 WHERE id = 1`,
+  ],
+};

package/src/migrations.js

@@ -1,4 +1,10 @@
 const JOURNAL_TABLE = 'yuncms_schema_migrations';
+const ATTEMPT_TABLE = 'yuncms_schema_migration_attempts';
+
+function truncateErrorMessage(value, maxLength = 1000) {
+  const message = String(value ?? 'Migration failed');
+  return message.length > maxLength ? message.slice(0, maxLength) : message;
+}
 
 export async function ensureMigrationJournal(database) {
   await database.query(`
@@ -7,6 +13,20 @@ export async function ensureMigrationJournal(database) {
       applied_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3)
     ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
   `);
+
+  await database.query(`
+    CREATE TABLE IF NOT EXISTS ${ATTEMPT_TABLE} (
+      migration_id VARCHAR(191) NOT NULL PRIMARY KEY,
+      status VARCHAR(16) NOT NULL,
+      statement_index INT UNSIGNED NOT NULL DEFAULT 0,
+      started_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+      finished_at DATETIME(3) NULL,
+      error_code VARCHAR(128) NULL,
+      error_message VARCHAR(1000) NULL,
+      CONSTRAINT chk_yuncms_schema_migration_attempt_status
+        CHECK (status IN ('applying', 'applied', 'failed'))
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
+  `);
 }
 
 export async function readAppliedMigrations(database) {
@@ -14,6 +34,15 @@ export async function readAppliedMigrations(database) {
   return new Set(rows.map((row) => row.id));
 }
 
+export async function readMigrationAttempts(database) {
+  const [rows] = await database.query(
+    `SELECT migration_id, status, statement_index, started_at, finished_at, error_code, error_message
+     FROM ${ATTEMPT_TABLE}
+     ORDER BY started_at ASC, migration_id ASC`,
+  );
+  return rows;
+}
+
 export function validateMigration(migration) {
   if (!migration || typeof migration !== 'object') throw new Error('Migration must be an object');
   if (!migration.id || typeof migration.id !== 'string') throw new Error('Migration id is required');
@@ -26,23 +55,102 @@ export function validateMigration(migration) {
   return migration;
 }
 
+function migrationRecoveryError(attempts) {
+  const ids = attempts.map((attempt) => attempt.migration_id);
+  const error = new Error(
+    `Database contains an incomplete migration attempt and must be restored before retrying: ${ids.join(', ')}`,
+  );
+  error.code = 'DATABASE_MIGRATION_RECOVERY_REQUIRED';
+  error.migrationAttempts = attempts.map((attempt) => ({ ...attempt }));
+  return error;
+}
+
+async function assertNoIncompleteMigrationAttempts(database, applied, { allowMissingJournal = false } = {}) {
+  let attempts;
+  try {
+    attempts = await readMigrationAttempts(database);
+  } catch (error) {
+    if (allowMissingJournal && error?.code === 'ER_NO_SUCH_TABLE') return;
+    throw error;
+  }
+  const inconsistent = attempts.filter((attempt) => !applied.has(attempt.migration_id));
+  if (inconsistent.length > 0) throw migrationRecoveryError(inconsistent);
+}
+
+async function beginMigrationAttempt(database, migration) {
+  await database.query(
+    `INSERT INTO ${ATTEMPT_TABLE}
+       (migration_id, status, statement_index, started_at, finished_at, error_code, error_message)
+     VALUES (?, 'applying', 0, CURRENT_TIMESTAMP(3), NULL, NULL, NULL)`,
+    [migration.id],
+  );
+}
+
+async function advanceMigrationAttempt(database, migrationId, statementIndex) {
+  await database.query(
+    `UPDATE ${ATTEMPT_TABLE}
+     SET statement_index = ?
+     WHERE migration_id = ? AND status = 'applying'`,
+    [statementIndex, migrationId],
+  );
+}
+
+async function completeMigrationAttempt(database, migrationId) {
+  await database.query(
+    `UPDATE ${ATTEMPT_TABLE}
+     SET status = 'applied', finished_at = CURRENT_TIMESTAMP(3), error_code = NULL, error_message = NULL
+     WHERE migration_id = ?`,
+    [migrationId],
+  );
+}
+
+async function failMigrationAttempt(database, migrationId, error) {
+  await database.query(
+    `UPDATE ${ATTEMPT_TABLE}
+     SET status = 'failed', finished_at = CURRENT_TIMESTAMP(3), error_code = ?, error_message = ?
+     WHERE migration_id = ?`,
+    [
+      error?.code == null ? null : String(error.code).slice(0, 128),
+      truncateErrorMessage(error?.message),
+      migrationId,
+    ],
+  );
+}
+
 export async function applyMigrations(database, migrations) {
   if (!database) throw new Error('Database handle is required');
   if (!Array.isArray(migrations)) throw new Error('Migrations must be an array');
 
   await ensureMigrationJournal(database);
   const applied = await readAppliedMigrations(database);
+  await assertNoIncompleteMigrationAttempts(database, applied);
   const newlyApplied = [];
 
   for (const rawMigration of migrations) {
     const migration = validateMigration(rawMigration);
     if (applied.has(migration.id)) continue;
 
-    for (const statement of migration.statements) {
-      await database.query(statement);
+    await beginMigrationAttempt(database, migration);
+
+    try {
+      for (let index = 0; index < migration.statements.length; index += 1) {
+        await database.query(migration.statements[index]);
+        await advanceMigrationAttempt(database, migration.id, index + 1);
+      }
+
+      await database.query(`INSERT INTO ${JOURNAL_TABLE} (id) VALUES (?)`, [migration.id]);
+      await completeMigrationAttempt(database, migration.id);
+    } catch (error) {
+      try {
+        await failMigrationAttempt(database, migration.id, error);
+      } catch {
+        // The original migration error remains the source of truth. A stale 'applying'
+        // row still fails closed on the next bootstrap and requires restore/recovery.
+      }
+      error.migrationId ||= migration.id;
+      throw error;
     }
 
-    await database.query(`INSERT INTO ${JOURNAL_TABLE} (id) VALUES (?)`, [migration.id]);
     applied.add(migration.id);
     newlyApplied.push(migration.id);
   }
@@ -68,6 +176,8 @@ export async function assertMigrationsApplied(database, requiredMigrationIds) {
     throw error;
   }
 
+  await assertNoIncompleteMigrationAttempts(database, applied, { allowMissingJournal: true });
+
   const missing = requiredMigrationIds.filter((id) => !applied.has(id));
 
   if (missing.length > 0) {

package/src/query.js

@@ -7,6 +7,18 @@ const FILTER_OPERATORS = new Set([
   '_contains', '_starts_with', '_ends_with',
 ]);
 
+export const QUERY_LIMITS = Object.freeze({
+  defaultLimit: 100,
+  maxLimit: 500,
+  maxFields: 100,
+  maxRelationExpansions: 20,
+  maxSortFields: 20,
+  maxOffset: 1_000_000,
+  maxFilterDepth: 8,
+  maxFilterNodes: 100,
+  maxInValues: 100,
+});
+
 function queryError(message, path = null) {
   const error = new Error(message);
   error.code = 'INVALID_QUERY';
@@ -14,11 +26,14 @@ function queryError(message, path = null) {
   return error;
 }
 
-function normalizeDelimited(value, label) {
+function normalizeDelimited(value, label, { maxItems }) {
   if (value == null || value === '') return null;
   const values = Array.isArray(value) ? value : String(value).split(',');
   const normalized = values.map((item) => String(item).trim()).filter(Boolean);
   if (normalized.length === 0) throw queryError(`${label} cannot be empty`, label);
+  if (normalized.length > maxItems) {
+    throw queryError(`${label} cannot contain more than ${maxItems} entries`, label);
+  }
   return normalized;
 }
 
@@ -50,7 +65,8 @@ function normalizeFilter(value) {
   return value;
 }
 
-export function parseItemsQuery(raw = {}, { defaultLimit = 100, maxLimit = 500 } = {}) {
+export function parseItemsQuery(raw = {}, options = {}) {
+  const limits = { ...QUERY_LIMITS, ...options };
   if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
     throw queryError('Query must be an object');
   }
@@ -60,11 +76,19 @@ export function parseItemsQuery(raw = {}, { defaultLimit = 100, maxLimit = 500 }
   }
 
   return {
-    fields: normalizeDelimited(raw.fields, 'fields'),
+    fields: normalizeDelimited(raw.fields, 'fields', { maxItems: limits.maxFields }),
     filter: normalizeFilter(raw.filter),
-    sort: normalizeDelimited(raw.sort, 'sort'),
-    limit: normalizeInteger(raw.limit, defaultLimit, { label: 'limit', min: 1, max: maxLimit }),
-    offset: normalizeInteger(raw.offset, 0, { label: 'offset', min: 0, max: Number.MAX_SAFE_INTEGER }),
+    sort: normalizeDelimited(raw.sort, 'sort', { maxItems: limits.maxSortFields }),
+    limit: normalizeInteger(raw.limit, limits.defaultLimit, {
+      label: 'limit',
+      min: 1,
+      max: limits.maxLimit,
+    }),
+    offset: normalizeInteger(raw.offset, 0, {
+      label: 'offset',
+      min: 0,
+      max: limits.maxOffset,
+    }),
   };
 }
 
@@ -105,7 +129,7 @@ function escapeLike(value) {
   return String(value).replace(/[\\%_]/g, '\\$&');
 }
 
-function compileOperator(fieldSql, operator, value, path) {
+function compileOperator(fieldSql, operator, value, path, limits) {
   if (!FILTER_OPERATORS.has(operator)) throw queryError(`Unknown filter operator: ${operator}`, path);
 
   switch (operator) {
@@ -122,6 +146,9 @@ function compileOperator(fieldSql, operator, value, path) {
     case '_in':
     case '_nin': {
       if (!Array.isArray(value)) throw queryError(`${operator} requires an array`, path);
+      if (value.length > limits.maxInValues) {
+        throw queryError(`${operator} accepts at most ${limits.maxInValues} values`, path);
+      }
       if (value.length === 0) return { sql: operator === '_in' ? '0 = 1' : '1 = 1', params: [] };
       const placeholders = value.map(() => '?').join(', ');
       return {
@@ -146,10 +173,18 @@ function compileOperator(fieldSql, operator, value, path) {
   }
 }
 
-function compileFilterObject(filter, schema, path = 'filter') {
+function compileFilterObject(filter, schema, path, limits, state, depth) {
   if (!filter || typeof filter !== 'object' || Array.isArray(filter)) {
     throw queryError('Filter node must be an object', path);
   }
+  if (depth > limits.maxFilterDepth) {
+    throw queryError(`Filter depth cannot exceed ${limits.maxFilterDepth}`, path);
+  }
+
+  state.nodes += 1;
+  if (state.nodes > limits.maxFilterNodes) {
+    throw queryError(`Filter cannot contain more than ${limits.maxFilterNodes} nodes`, path);
+  }
 
   const fragments = [];
   const params = [];
@@ -160,7 +195,7 @@ function compileFilterObject(filter, schema, path = 'filter') {
         throw queryError(`${key} requires a non-empty array`, `${path}.${key}`);
       }
       const children = value.map((child, index) =>
-        compileFilterObject(child, schema, `${path}.${key}.${index}`));
+        compileFilterObject(child, schema, `${path}.${key}.${index}`, limits, state, depth + 1));
       fragments.push(`(${children.map((child) => child.sql).join(key === '_and' ? ' AND ' : ' OR ')})`);
       for (const child of children) params.push(...child.params);
       continue;
@@ -174,7 +209,13 @@ function compileFilterObject(filter, schema, path = 'filter') {
     const fieldSql = quoteIdentifier(key, 'field name');
     const fieldFragments = [];
     for (const [operator, operatorValue] of Object.entries(value)) {
-      const compiled = compileOperator(fieldSql, operator, operatorValue, `${path}.${key}.${operator}`);
+      const compiled = compileOperator(
+        fieldSql,
+        operator,
+        operatorValue,
+        `${path}.${key}.${operator}`,
+        limits,
+      );
       fieldFragments.push(compiled.sql);
       params.push(...compiled.params);
     }
@@ -186,8 +227,9 @@ function compileFilterObject(filter, schema, path = 'filter') {
   return { sql: fragments.join(' AND '), params };
 }
 
-export function compileFilter(filter, schema) {
+export function compileFilter(filter, schema, options = {}) {
   if (!filter) return { sql: '', params: [] };
-  const compiled = compileFilterObject(filter, schema);
+  const limits = { ...QUERY_LIMITS, ...options };
+  const compiled = compileFilterObject(filter, schema, 'filter', limits, { nodes: 0 }, 1);
   return { sql: ` WHERE ${compiled.sql}`, params: compiled.params };
 }