@objectstack/plugin-security 2.0.4

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/permission-evaluator.ts","../src/rls-compiler.ts","../src/field-masker.ts","../src/security-plugin.ts"],"sourcesContent":["// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type { PermissionSet, ObjectPermission, FieldPermission } from '@objectstack/spec/security';\n\n/**\n * Operation type mapping to permission checks\n */\nconst OPERATION_TO_PERMISSION: Record<string, keyof ObjectPermission> = {\n  find: 'allowRead',\n  findOne: 'allowRead',\n  count: 'allowRead',\n  aggregate: 'allowRead',\n  insert: 'allowCreate',\n  update: 'allowEdit',\n  delete: 'allowDelete',\n};\n\n/**\n * PermissionEvaluator\n * \n * Runtime evaluator for PermissionSet definitions.\n * Resolves aggregated permissions from roles to concrete allow/deny decisions.\n */\nexport class PermissionEvaluator {\n  /**\n   * Check if an operation is allowed on an object for the given permission sets.\n   * Uses \"most permissive\" merging: if ANY permission set allows, it's allowed.\n   */\n  checkObjectPermission(\n    operation: string,\n    objectName: string,\n    permissionSets: PermissionSet[]\n  ): boolean {\n    const permKey = OPERATION_TO_PERMISSION[operation];\n    if (!permKey) return true; // Unknown operations are allowed by default\n\n    for (const ps of permissionSets) {\n      const objPerm = ps.objects?.[objectName];\n      if (objPerm) {\n        // Check if modifyAllRecords is set (super-user bypass for write ops)\n        if (['allowEdit', 'allowDelete'].includes(permKey) && objPerm.modifyAllRecords) {\n          return true;\n        }\n        // Check if viewAllRecords is set (super-user bypass for read ops)\n        if (permKey === 'allowRead' && (objPerm.viewAllRecords || objPerm.modifyAllRecords)) {\n          return true;\n        }\n        // Check the specific permission\n        if (objPerm[permKey]) {\n          return true;\n        }\n      }\n    }\n\n    return false;\n  }\n\n  /**\n   * Get the merged field permissions for an object.\n   * Returns a map of field names to their effective permissions.\n   * Uses \"most permissive\" merging.\n   */\n  getFieldPermissions(\n    objectName: string,\n    permissionSets: PermissionSet[]\n  ): Record<string, FieldPermission> {\n    const result: Record<string, FieldPermission> = {};\n\n    for (const ps of permissionSets) {\n      if (!ps.fields) continue;\n\n      for (const [key, perm] of Object.entries(ps.fields)) {\n        // Field keys are in format: \"object_name.field_name\"\n        if (!key.startsWith(`${objectName}.`)) continue;\n        const fieldName = key.substring(objectName.length + 1);\n\n        if (!result[fieldName]) {\n          result[fieldName] = { readable: false, editable: false };\n        }\n\n        // Most permissive merge\n        if (perm.readable) result[fieldName].readable = true;\n        if (perm.editable) result[fieldName].editable = true;\n      }\n    }\n\n    return result;\n  }\n\n  /**\n   * Resolve permission sets for a list of role names from metadata.\n   */\n  resolvePermissionSets(\n    roles: string[],\n    metadataService: any\n  ): PermissionSet[] {\n    const result: PermissionSet[] = [];\n\n    // Get all permission sets from metadata\n    const allPermSets = metadataService.list?.('permissions') || [];\n\n    for (const ps of allPermSets) {\n      // A permission set is relevant if it's a profile assigned to any of the user's roles,\n      // or if the role name matches the permission set name\n      if (roles.includes(ps.name)) {\n        result.push(ps);\n      }\n    }\n\n    return result;\n  }\n}\n","// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type { RowLevelSecurityPolicy } from '@objectstack/spec/security';\nimport type { ExecutionContext } from '@objectstack/spec/kernel';\n\n/**\n * RLS User Context\n * Variables available for RLS expression evaluation.\n */\ninterface RLSUserContext {\n  id?: string;\n  tenant_id?: string;\n  roles?: string[];\n  [key: string]: unknown;\n}\n\n/**\n * RLSCompiler\n * \n * Compiles Row-Level Security policy expressions into query filters.\n * Converts `using` / `check` expressions into ObjectQL-compatible filter conditions.\n */\nexport class RLSCompiler {\n  /**\n   * Compile RLS policies into a query filter for the given user context.\n   * Multiple policies for the same object/operation are OR-combined (any match allows access).\n   */\n  compileFilter(\n    policies: RowLevelSecurityPolicy[],\n    executionContext?: ExecutionContext\n  ): Record<string, unknown> | null {\n    if (policies.length === 0) return null;\n\n    const userCtx: RLSUserContext = {\n      id: executionContext?.userId,\n      tenant_id: executionContext?.tenantId,\n      roles: executionContext?.roles,\n    };\n\n    const filters: Record<string, unknown>[] = [];\n\n    for (const policy of policies) {\n      if (!policy.using) continue;\n      const filter = this.compileExpression(policy.using, userCtx);\n      if (filter) {\n        filters.push(filter);\n      }\n    }\n\n    if (filters.length === 0) return null;\n    if (filters.length === 1) return filters[0];\n\n    // Multiple policies: OR-combine (any policy allows access)\n    return { $or: filters };\n  }\n\n  /**\n   * Compile a single RLS expression into a query filter.\n   * \n   * Supports simple expressions like:\n   * - \"field_name = current_user.property\"\n   * - \"field_name IN (current_user.array_property)\"\n   * - \"field_name = 'literal_value'\"\n   */\n  compileExpression(\n    expression: string,\n    userCtx: RLSUserContext\n  ): Record<string, unknown> | null {\n    if (!expression) return null;\n\n    // Handle simple equality: \"field = current_user.property\"\n    const eqMatch = expression.match(/^\\s*(\\w+)\\s*=\\s*current_user\\.(\\w+)\\s*$/);\n    if (eqMatch) {\n      const [, field, prop] = eqMatch;\n      const value = userCtx[prop];\n      if (value === undefined) return null;\n      return { [field]: value };\n    }\n\n    // Handle literal equality: \"field = 'value'\"\n    const litMatch = expression.match(/^\\s*(\\w+)\\s*=\\s*'([^']*)'\\s*$/);\n    if (litMatch) {\n      const [, field, value] = litMatch;\n      return { [field]: value };\n    }\n\n    // Handle IN: \"field IN (current_user.array_property)\"\n    const inMatch = expression.match(/^\\s*(\\w+)\\s+IN\\s+\\(\\s*current_user\\.(\\w+)\\s*\\)\\s*$/i);\n    if (inMatch) {\n      const [, field, prop] = inMatch;\n      const value = userCtx[prop];\n      if (!Array.isArray(value)) return null;\n      return { [field]: { $in: value } };\n    }\n\n    // Unsupported expression: return null (no additional RLS filter applied).\n    // Note: callers should treat absence of RLS policies as \"allow all\" only when\n    // no policies are defined. If policies exist but cannot be compiled, the caller\n    // may want to deny access as a safety measure.\n    return null;\n  }\n\n  /**\n   * Get applicable RLS policies for a given object and operation.\n   */\n  getApplicablePolicies(\n    objectName: string,\n    operation: string,\n    allPolicies: RowLevelSecurityPolicy[]\n  ): RowLevelSecurityPolicy[] {\n    // Map engine operation to RLS operation type\n    const rlsOp = this.mapOperationToRLS(operation);\n\n    return allPolicies.filter(policy => {\n      // Check object match\n      if (policy.object !== objectName && policy.object !== '*') return false;\n\n      // Check operation match\n      if (policy.operation === 'all') return true;\n      if (policy.operation === rlsOp) return true;\n\n      return false;\n    });\n  }\n\n  private mapOperationToRLS(operation: string): string {\n    switch (operation) {\n      case 'find':\n      case 'findOne':\n      case 'count':\n      case 'aggregate':\n        return 'select';\n      case 'insert':\n        return 'insert';\n      case 'update':\n        return 'update';\n      case 'delete':\n        return 'delete';\n      default:\n        return 'select';\n    }\n  }\n}\n","// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type { FieldPermission } from '@objectstack/spec/security';\n\n/**\n * FieldMasker\n * \n * Applies field-level security by stripping restricted fields from query results.\n */\nexport class FieldMasker {\n  /**\n   * Mask fields in query results based on field permissions.\n   * Removes fields that the user does not have read access to.\n   */\n  maskResults(\n    results: any | any[],\n    fieldPermissions: Record<string, FieldPermission>,\n    _objectName: string\n  ): any | any[] {\n    // If no field permissions defined, return results as-is\n    if (Object.keys(fieldPermissions).length === 0) return results;\n\n    // Get list of non-readable fields\n    const hiddenFields = Object.entries(fieldPermissions)\n      .filter(([, perm]) => !perm.readable)\n      .map(([field]) => field);\n\n    if (hiddenFields.length === 0) return results;\n\n    if (Array.isArray(results)) {\n      return results.map(record => this.maskRecord(record, hiddenFields));\n    }\n\n    return this.maskRecord(results, hiddenFields);\n  }\n\n  /**\n   * Get non-editable fields for use in write operations.\n   * Returns a list of field names that should be stripped from incoming data.\n   */\n  getNonEditableFields(\n    fieldPermissions: Record<string, FieldPermission>\n  ): string[] {\n    return Object.entries(fieldPermissions)\n      .filter(([, perm]) => !perm.editable)\n      .map(([field]) => field);\n  }\n\n  /**\n   * Strip non-editable fields from write data.\n   */\n  stripNonEditableFields(\n    data: Record<string, any>,\n    fieldPermissions: Record<string, FieldPermission>\n  ): Record<string, any> {\n    const nonEditable = this.getNonEditableFields(fieldPermissions);\n    if (nonEditable.length === 0) return data;\n\n    const result = { ...data };\n    for (const field of nonEditable) {\n      delete result[field];\n    }\n    return result;\n  }\n\n  private maskRecord(record: any, hiddenFields: string[]): any {\n    if (!record || typeof record !== 'object') return record;\n\n    const result = { ...record };\n    for (const field of hiddenFields) {\n      delete result[field];\n    }\n    return result;\n  }\n}\n","// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport { Plugin, PluginContext } from '@objectstack/core';\nimport type { PermissionSet, RowLevelSecurityPolicy } from '@objectstack/spec/security';\nimport { PermissionEvaluator } from './permission-evaluator.js';\nimport { RLSCompiler } from './rls-compiler.js';\nimport { FieldMasker } from './field-masker.js';\n\n/**\n * SecurityPlugin\n * \n * Provides RBAC, Row-Level Security, and Field-Level Security runtime.\n * Registers as an engine middleware on the ObjectQL engine.\n * \n * This plugin is fully optional — without it, the system operates\n * without permission checks (same as current behavior).\n * \n * Dependencies:\n * - objectql service (ObjectQL engine with middleware support)\n * - metadata service (MetadataFacade for reading permission sets and RLS policies)\n */\nexport class SecurityPlugin implements Plugin {\n  name = 'com.objectstack.security';\n  type = 'standard';\n  version = '1.0.0';\n  dependencies = ['com.objectstack.engine.objectql'];\n\n  private permissionEvaluator = new PermissionEvaluator();\n  private rlsCompiler = new RLSCompiler();\n  private fieldMasker = new FieldMasker();\n\n  async init(ctx: PluginContext): Promise<void> {\n    ctx.logger.info('Initializing Security Plugin...');\n    \n    // Register security services\n    ctx.registerService('security.permissions', this.permissionEvaluator);\n    ctx.registerService('security.rls', this.rlsCompiler);\n    ctx.registerService('security.fieldMasker', this.fieldMasker);\n    \n    ctx.logger.info('Security Plugin initialized');\n  }\n\n  async start(ctx: PluginContext): Promise<void> {\n    ctx.logger.info('Starting Security Plugin...');\n\n    // Get required services\n    let ql: any;\n    let metadata: any;\n\n    try {\n      ql = ctx.getService('objectql');\n      metadata = ctx.getService('metadata');\n    } catch (e) {\n      ctx.logger.warn('ObjectQL or metadata service not available, security middleware not registered');\n      return;\n    }\n\n    if (!ql || typeof ql.registerMiddleware !== 'function') {\n      ctx.logger.warn('ObjectQL engine does not support middleware, security middleware not registered');\n      return;\n    }\n\n    // Register security middleware\n    ql.registerMiddleware(async (opCtx: any, next: () => Promise<void>) => {\n      // System operations bypass security\n      if (opCtx.context?.isSystem) {\n        return next();\n      }\n\n      const roles = opCtx.context?.roles ?? [];\n\n      // Skip security checks if no roles (anonymous/unauthenticated)\n      // The auth middleware should handle authentication separately\n      if (roles.length === 0 && !opCtx.context?.userId) {\n        return next();\n      }\n\n      // 1. Resolve permission sets for the user's roles\n      let permissionSets: PermissionSet[] = [];\n      try {\n        permissionSets = this.permissionEvaluator.resolvePermissionSets(roles, metadata);\n      } catch (e) {\n        // If metadata service is misconfigured, log and continue without permission checks\n        // rather than blocking all operations\n        return next();\n      }\n\n      // 2. CRUD permission check\n      if (permissionSets.length > 0) {\n        const allowed = this.permissionEvaluator.checkObjectPermission(\n          opCtx.operation,\n          opCtx.object,\n          permissionSets\n        );\n\n        if (!allowed) {\n          throw new Error(\n            `[Security] Access denied: operation '${opCtx.operation}' on object '${opCtx.object}' ` +\n            `is not permitted for roles [${roles.join(', ')}]`\n          );\n        }\n      }\n\n      // 3. RLS filter injection\n      const allRlsPolicies = this.collectRLSPolicies(permissionSets, opCtx.object, opCtx.operation);\n      if (allRlsPolicies.length > 0 && opCtx.ast) {\n        const rlsFilter = this.rlsCompiler.compileFilter(allRlsPolicies, opCtx.context);\n        if (rlsFilter) {\n          if (opCtx.ast.where) {\n            opCtx.ast.where = { $and: [opCtx.ast.where, rlsFilter] };\n          } else {\n            opCtx.ast.where = rlsFilter;\n          }\n        }\n      }\n\n      await next();\n\n      // 4. Field-level security: mask restricted fields in read results\n      if (opCtx.result && ['find', 'findOne'].includes(opCtx.operation)) {\n        const fieldPerms = this.permissionEvaluator.getFieldPermissions(opCtx.object, permissionSets);\n        if (Object.keys(fieldPerms).length > 0) {\n          opCtx.result = this.fieldMasker.maskResults(opCtx.result, fieldPerms, opCtx.object);\n        }\n      }\n    });\n\n    ctx.logger.info('Security middleware registered on ObjectQL engine');\n  }\n\n  async destroy(): Promise<void> {\n    // No cleanup needed\n  }\n\n  /**\n   * Collect all RLS policies from permission sets applicable to the given object/operation.\n   */\n  private collectRLSPolicies(\n    permissionSets: PermissionSet[],\n    objectName: string,\n    operation: string\n  ): RowLevelSecurityPolicy[] {\n    const allPolicies: RowLevelSecurityPolicy[] = [];\n\n    for (const ps of permissionSets) {\n      if (ps.rowLevelSecurity) {\n        allPolicies.push(...ps.rowLevelSecurity);\n      }\n    }\n\n    return this.rlsCompiler.getApplicablePolicies(objectName, operation, allPolicies);\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@objectstack/plugin-security",
+  "version": "2.0.4",
+  "license": "Apache-2.0",
+  "description": "Security Plugin for ObjectStack — RBAC, RLS, and Field-Level Security Runtime",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@objectstack/core": "2.0.4",
+    "@objectstack/spec": "2.0.4"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.2",
+    "typescript": "^5.0.0",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "tsup --config ../../../tsup.config.ts",
+    "test": "vitest run"
+  }
+}

package/src/field-masker.ts

@@ -0,0 +1,75 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { FieldPermission } from '@objectstack/spec/security';
+
+/**
+ * FieldMasker
+ * 
+ * Applies field-level security by stripping restricted fields from query results.
+ */
+export class FieldMasker {
+  /**
+   * Mask fields in query results based on field permissions.
+   * Removes fields that the user does not have read access to.
+   */
+  maskResults(
+    results: any | any[],
+    fieldPermissions: Record<string, FieldPermission>,
+    _objectName: string
+  ): any | any[] {
+    // If no field permissions defined, return results as-is
+    if (Object.keys(fieldPermissions).length === 0) return results;
+
+    // Get list of non-readable fields
+    const hiddenFields = Object.entries(fieldPermissions)
+      .filter(([, perm]) => !perm.readable)
+      .map(([field]) => field);
+
+    if (hiddenFields.length === 0) return results;
+
+    if (Array.isArray(results)) {
+      return results.map(record => this.maskRecord(record, hiddenFields));
+    }
+
+    return this.maskRecord(results, hiddenFields);
+  }
+
+  /**
+   * Get non-editable fields for use in write operations.
+   * Returns a list of field names that should be stripped from incoming data.
+   */
+  getNonEditableFields(
+    fieldPermissions: Record<string, FieldPermission>
+  ): string[] {
+    return Object.entries(fieldPermissions)
+      .filter(([, perm]) => !perm.editable)
+      .map(([field]) => field);
+  }
+
+  /**
+   * Strip non-editable fields from write data.
+   */
+  stripNonEditableFields(
+    data: Record<string, any>,
+    fieldPermissions: Record<string, FieldPermission>
+  ): Record<string, any> {
+    const nonEditable = this.getNonEditableFields(fieldPermissions);
+    if (nonEditable.length === 0) return data;
+
+    const result = { ...data };
+    for (const field of nonEditable) {
+      delete result[field];
+    }
+    return result;
+  }
+
+  private maskRecord(record: any, hiddenFields: string[]): any {
+    if (!record || typeof record !== 'object') return record;
+
+    const result = { ...record };
+    for (const field of hiddenFields) {
+      delete result[field];
+    }
+    return result;
+  }
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * @objectstack/plugin-security
+ * 
+ * Security Plugin for ObjectStack
+ * Provides RBAC, Row-Level Security (RLS), and Field-Level Security runtime.
+ */
+
+export { SecurityPlugin } from './security-plugin.js';
+export { PermissionEvaluator } from './permission-evaluator.js';
+export { RLSCompiler } from './rls-compiler.js';
+export { FieldMasker } from './field-masker.js';

package/src/permission-evaluator.ts

@@ -0,0 +1,112 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { PermissionSet, ObjectPermission, FieldPermission } from '@objectstack/spec/security';
+
+/**
+ * Operation type mapping to permission checks
+ */
+const OPERATION_TO_PERMISSION: Record<string, keyof ObjectPermission> = {
+  find: 'allowRead',
+  findOne: 'allowRead',
+  count: 'allowRead',
+  aggregate: 'allowRead',
+  insert: 'allowCreate',
+  update: 'allowEdit',
+  delete: 'allowDelete',
+};
+
+/**
+ * PermissionEvaluator
+ * 
+ * Runtime evaluator for PermissionSet definitions.
+ * Resolves aggregated permissions from roles to concrete allow/deny decisions.
+ */
+export class PermissionEvaluator {
+  /**
+   * Check if an operation is allowed on an object for the given permission sets.
+   * Uses "most permissive" merging: if ANY permission set allows, it's allowed.
+   */
+  checkObjectPermission(
+    operation: string,
+    objectName: string,
+    permissionSets: PermissionSet[]
+  ): boolean {
+    const permKey = OPERATION_TO_PERMISSION[operation];
+    if (!permKey) return true; // Unknown operations are allowed by default
+
+    for (const ps of permissionSets) {
+      const objPerm = ps.objects?.[objectName];
+      if (objPerm) {
+        // Check if modifyAllRecords is set (super-user bypass for write ops)
+        if (['allowEdit', 'allowDelete'].includes(permKey) && objPerm.modifyAllRecords) {
+          return true;
+        }
+        // Check if viewAllRecords is set (super-user bypass for read ops)
+        if (permKey === 'allowRead' && (objPerm.viewAllRecords || objPerm.modifyAllRecords)) {
+          return true;
+        }
+        // Check the specific permission
+        if (objPerm[permKey]) {
+          return true;
+        }
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Get the merged field permissions for an object.
+   * Returns a map of field names to their effective permissions.
+   * Uses "most permissive" merging.
+   */
+  getFieldPermissions(
+    objectName: string,
+    permissionSets: PermissionSet[]
+  ): Record<string, FieldPermission> {
+    const result: Record<string, FieldPermission> = {};
+
+    for (const ps of permissionSets) {
+      if (!ps.fields) continue;
+
+      for (const [key, perm] of Object.entries(ps.fields)) {
+        // Field keys are in format: "object_name.field_name"
+        if (!key.startsWith(`${objectName}.`)) continue;
+        const fieldName = key.substring(objectName.length + 1);
+
+        if (!result[fieldName]) {
+          result[fieldName] = { readable: false, editable: false };
+        }
+
+        // Most permissive merge
+        if (perm.readable) result[fieldName].readable = true;
+        if (perm.editable) result[fieldName].editable = true;
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Resolve permission sets for a list of role names from metadata.
+   */
+  resolvePermissionSets(
+    roles: string[],
+    metadataService: any
+  ): PermissionSet[] {
+    const result: PermissionSet[] = [];
+
+    // Get all permission sets from metadata
+    const allPermSets = metadataService.list?.('permissions') || [];
+
+    for (const ps of allPermSets) {
+      // A permission set is relevant if it's a profile assigned to any of the user's roles,
+      // or if the role name matches the permission set name
+      if (roles.includes(ps.name)) {
+        result.push(ps);
+      }
+    }
+
+    return result;
+  }
+}

package/src/rls-compiler.ts

@@ -0,0 +1,143 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { RowLevelSecurityPolicy } from '@objectstack/spec/security';
+import type { ExecutionContext } from '@objectstack/spec/kernel';
+
+/**
+ * RLS User Context
+ * Variables available for RLS expression evaluation.
+ */
+interface RLSUserContext {
+  id?: string;
+  tenant_id?: string;
+  roles?: string[];
+  [key: string]: unknown;
+}
+
+/**
+ * RLSCompiler
+ * 
+ * Compiles Row-Level Security policy expressions into query filters.
+ * Converts `using` / `check` expressions into ObjectQL-compatible filter conditions.
+ */
+export class RLSCompiler {
+  /**
+   * Compile RLS policies into a query filter for the given user context.
+   * Multiple policies for the same object/operation are OR-combined (any match allows access).
+   */
+  compileFilter(
+    policies: RowLevelSecurityPolicy[],
+    executionContext?: ExecutionContext
+  ): Record<string, unknown> | null {
+    if (policies.length === 0) return null;
+
+    const userCtx: RLSUserContext = {
+      id: executionContext?.userId,
+      tenant_id: executionContext?.tenantId,
+      roles: executionContext?.roles,
+    };
+
+    const filters: Record<string, unknown>[] = [];
+
+    for (const policy of policies) {
+      if (!policy.using) continue;
+      const filter = this.compileExpression(policy.using, userCtx);
+      if (filter) {
+        filters.push(filter);
+      }
+    }
+
+    if (filters.length === 0) return null;
+    if (filters.length === 1) return filters[0];
+
+    // Multiple policies: OR-combine (any policy allows access)
+    return { $or: filters };
+  }
+
+  /**
+   * Compile a single RLS expression into a query filter.
+   * 
+   * Supports simple expressions like:
+   * - "field_name = current_user.property"
+   * - "field_name IN (current_user.array_property)"
+   * - "field_name = 'literal_value'"
+   */
+  compileExpression(
+    expression: string,
+    userCtx: RLSUserContext
+  ): Record<string, unknown> | null {
+    if (!expression) return null;
+
+    // Handle simple equality: "field = current_user.property"
+    const eqMatch = expression.match(/^\s*(\w+)\s*=\s*current_user\.(\w+)\s*$/);
+    if (eqMatch) {
+      const [, field, prop] = eqMatch;
+      const value = userCtx[prop];
+      if (value === undefined) return null;
+      return { [field]: value };
+    }
+
+    // Handle literal equality: "field = 'value'"
+    const litMatch = expression.match(/^\s*(\w+)\s*=\s*'([^']*)'\s*$/);
+    if (litMatch) {
+      const [, field, value] = litMatch;
+      return { [field]: value };
+    }
+
+    // Handle IN: "field IN (current_user.array_property)"
+    const inMatch = expression.match(/^\s*(\w+)\s+IN\s+\(\s*current_user\.(\w+)\s*\)\s*$/i);
+    if (inMatch) {
+      const [, field, prop] = inMatch;
+      const value = userCtx[prop];
+      if (!Array.isArray(value)) return null;
+      return { [field]: { $in: value } };
+    }
+
+    // Unsupported expression: return null (no additional RLS filter applied).
+    // Note: callers should treat absence of RLS policies as "allow all" only when
+    // no policies are defined. If policies exist but cannot be compiled, the caller
+    // may want to deny access as a safety measure.
+    return null;
+  }
+
+  /**
+   * Get applicable RLS policies for a given object and operation.
+   */
+  getApplicablePolicies(
+    objectName: string,
+    operation: string,
+    allPolicies: RowLevelSecurityPolicy[]
+  ): RowLevelSecurityPolicy[] {
+    // Map engine operation to RLS operation type
+    const rlsOp = this.mapOperationToRLS(operation);
+
+    return allPolicies.filter(policy => {
+      // Check object match
+      if (policy.object !== objectName && policy.object !== '*') return false;
+
+      // Check operation match
+      if (policy.operation === 'all') return true;
+      if (policy.operation === rlsOp) return true;
+
+      return false;
+    });
+  }
+
+  private mapOperationToRLS(operation: string): string {
+    switch (operation) {
+      case 'find':
+      case 'findOne':
+      case 'count':
+      case 'aggregate':
+        return 'select';
+      case 'insert':
+        return 'insert';
+      case 'update':
+        return 'update';
+      case 'delete':
+        return 'delete';
+      default:
+        return 'select';
+    }
+  }
+}

package/src/security-plugin.ts

@@ -0,0 +1,153 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { Plugin, PluginContext } from '@objectstack/core';
+import type { PermissionSet, RowLevelSecurityPolicy } from '@objectstack/spec/security';
+import { PermissionEvaluator } from './permission-evaluator.js';
+import { RLSCompiler } from './rls-compiler.js';
+import { FieldMasker } from './field-masker.js';
+
+/**
+ * SecurityPlugin
+ * 
+ * Provides RBAC, Row-Level Security, and Field-Level Security runtime.
+ * Registers as an engine middleware on the ObjectQL engine.
+ * 
+ * This plugin is fully optional — without it, the system operates
+ * without permission checks (same as current behavior).
+ * 
+ * Dependencies:
+ * - objectql service (ObjectQL engine with middleware support)
+ * - metadata service (MetadataFacade for reading permission sets and RLS policies)
+ */
+export class SecurityPlugin implements Plugin {
+  name = 'com.objectstack.security';
+  type = 'standard';
+  version = '1.0.0';
+  dependencies = ['com.objectstack.engine.objectql'];
+
+  private permissionEvaluator = new PermissionEvaluator();
+  private rlsCompiler = new RLSCompiler();
+  private fieldMasker = new FieldMasker();
+
+  async init(ctx: PluginContext): Promise<void> {
+    ctx.logger.info('Initializing Security Plugin...');
+    
+    // Register security services
+    ctx.registerService('security.permissions', this.permissionEvaluator);
+    ctx.registerService('security.rls', this.rlsCompiler);
+    ctx.registerService('security.fieldMasker', this.fieldMasker);
+    
+    ctx.logger.info('Security Plugin initialized');
+  }
+
+  async start(ctx: PluginContext): Promise<void> {
+    ctx.logger.info('Starting Security Plugin...');
+
+    // Get required services
+    let ql: any;
+    let metadata: any;
+
+    try {
+      ql = ctx.getService('objectql');
+      metadata = ctx.getService('metadata');
+    } catch (e) {
+      ctx.logger.warn('ObjectQL or metadata service not available, security middleware not registered');
+      return;
+    }
+
+    if (!ql || typeof ql.registerMiddleware !== 'function') {
+      ctx.logger.warn('ObjectQL engine does not support middleware, security middleware not registered');
+      return;
+    }
+
+    // Register security middleware
+    ql.registerMiddleware(async (opCtx: any, next: () => Promise<void>) => {
+      // System operations bypass security
+      if (opCtx.context?.isSystem) {
+        return next();
+      }
+
+      const roles = opCtx.context?.roles ?? [];
+
+      // Skip security checks if no roles (anonymous/unauthenticated)
+      // The auth middleware should handle authentication separately
+      if (roles.length === 0 && !opCtx.context?.userId) {
+        return next();
+      }
+
+      // 1. Resolve permission sets for the user's roles
+      let permissionSets: PermissionSet[] = [];
+      try {
+        permissionSets = this.permissionEvaluator.resolvePermissionSets(roles, metadata);
+      } catch (e) {
+        // If metadata service is misconfigured, log and continue without permission checks
+        // rather than blocking all operations
+        return next();
+      }
+
+      // 2. CRUD permission check
+      if (permissionSets.length > 0) {
+        const allowed = this.permissionEvaluator.checkObjectPermission(
+          opCtx.operation,
+          opCtx.object,
+          permissionSets
+        );
+
+        if (!allowed) {
+          throw new Error(
+            `[Security] Access denied: operation '${opCtx.operation}' on object '${opCtx.object}' ` +
+            `is not permitted for roles [${roles.join(', ')}]`
+          );
+        }
+      }
+
+      // 3. RLS filter injection
+      const allRlsPolicies = this.collectRLSPolicies(permissionSets, opCtx.object, opCtx.operation);
+      if (allRlsPolicies.length > 0 && opCtx.ast) {
+        const rlsFilter = this.rlsCompiler.compileFilter(allRlsPolicies, opCtx.context);
+        if (rlsFilter) {
+          if (opCtx.ast.where) {
+            opCtx.ast.where = { $and: [opCtx.ast.where, rlsFilter] };
+          } else {
+            opCtx.ast.where = rlsFilter;
+          }
+        }
+      }
+
+      await next();
+
+      // 4. Field-level security: mask restricted fields in read results
+      if (opCtx.result && ['find', 'findOne'].includes(opCtx.operation)) {
+        const fieldPerms = this.permissionEvaluator.getFieldPermissions(opCtx.object, permissionSets);
+        if (Object.keys(fieldPerms).length > 0) {
+          opCtx.result = this.fieldMasker.maskResults(opCtx.result, fieldPerms, opCtx.object);
+        }
+      }
+    });
+
+    ctx.logger.info('Security middleware registered on ObjectQL engine');
+  }
+
+  async destroy(): Promise<void> {
+    // No cleanup needed
+  }
+
+  /**
+   * Collect all RLS policies from permission sets applicable to the given object/operation.
+   */
+  private collectRLSPolicies(
+    permissionSets: PermissionSet[],
+    objectName: string,
+    operation: string
+  ): RowLevelSecurityPolicy[] {
+    const allPolicies: RowLevelSecurityPolicy[] = [];
+
+    for (const ps of permissionSets) {
+      if (ps.rowLevelSecurity) {
+        allPolicies.push(...ps.rowLevelSecurity);
+      }
+    }
+
+    return this.rlsCompiler.getApplicablePolicies(objectName, operation, allPolicies);
+  }
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["dist", "node_modules", "**/*.test.ts"]
+}