Phase 4: Create plugin-security package with RBAC, RLS compiler, and field masker

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Author: Copilot

packages/plugins/plugin-security/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"
+    }
+  },
+  "scripts": {
+    "build": "tsup --config ../../../tsup.config.ts",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@objectstack/core": "workspace:*",
+    "@objectstack/spec": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.2",
+    "typescript": "^5.0.0",
+    "vitest": "^4.0.18"
+  }
+}

packages/plugins/plugin-security/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;
+  }
+}

packages/plugins/plugin-security/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';

packages/plugins/plugin-security/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;
+  }
+}

packages/plugins/plugin-security/src/rls-compiler.ts

@@ -0,0 +1,140 @@
+// 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 filter applied - fail-safe is to deny)
+    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';
+    }
+  }
+}