feat(acl-permissions): remove legacy ACL service, types, rules handling, and permissions factories, replace with updated utilities and proxy functions for enhanced control

Author: klerick

libs/acl-permissions/nestjs-acl-permissions/README.md

@@ -2,9 +2,12 @@
   "name": "@klerick/acl-json-api-nestjs",
   "version": "0.0.1",
   "dependencies": {
-    "tslib": "^2.3.0"
+    "@casl/ability": "^6.0.0"
   },
   "type": "commonjs",
   "main": "./src/index.js",
-  "typings": "./src/index.d.ts"
+  "typings": "./src/index.d.ts",
+  "peerDependencies": {
+    "@klerick/json-api-nestjs": "0.0.0"
+  }
 }

libs/acl-permissions/nestjs-acl-permissions/package.json

@@ -1,18 +1,57 @@
 {
   "name": "nestjs-acl-permissions",
   "$schema": "../../../node_modules/nx/schemas/project-schema.json",
-  "sourceRoot": "libs/nestjs-acl-permissions/src",
+  "sourceRoot": "libs/acl-permissions/nestjs-acl-permissions",
   "projectType": "library",
+  "implicitDependencies": ["json-api-nestjs"],
   "targets": {
+    "build-common": {
+      "dependsOn": ["^build", "^build-cjs", "^build-mjs"],
+      "executor": "@nx/js:tsc",
+      "outputs": ["{options.outputPath}"],
+      "options": {
+        "outputPath": "dist/{projectRoot}",
+        "tsConfig": "{projectRoot}/tsconfig.lib.json",
+        "packageJson": "{projectRoot}/package.json",
+        "main": "{projectRoot}/src/index.ts",
+        "assets": ["{projectRoot}/*.md"],
+        "generateExportsField": true,
+        "updateBuildableProjectDepsInPackageJson": false
+      }
+    },
     "build": {
+      "executor": "nx:run-commands",
+      "dependsOn": [
+        "build-common"
+      ],
+      "options": {
+        "outputPath": "dist/{projectRoot}",
+        "commands": [
+          {
+            "command": "node tools/scripts/prepare-package-json.mjs nestjs-acl-permissions"
+          },
+          {
+            "command": "mkdir -p node_modules/@klerick && rm -rf node_modules/@klerick/acl-json-api-nestjs",
+            "forwardAllArgs": false
+          },
+          {
+            "command": "ln -s $(pwd)/dist/{projectRoot} node_modules/@klerick/acl-json-api-nestjs",
+            "forwardAllArgs": false
+          }
+        ],
+        "cwd": "./",
+        "parallel": false
+      }
+    },
+    "build1": {
       "executor": "@nx/js:tsc",
       "outputs": ["{options.outputPath}"],
       "options": {
-        "outputPath": "dist/libs/nestjs-acl-permissions",
-        "tsConfig": "libs/nestjs-acl-permissions/tsconfig.lib.json",
-        "packageJson": "libs/nestjs-acl-permissions/package.json",
-        "main": "libs/nestjs-acl-permissions/src/index.ts",
-        "assets": ["libs/nestjs-acl-permissions/*.md"]
+        "outputPath": "dist/libs/acl-permissions/nestjs-acl-permissions",
+        "tsConfig": "libs/acl-permissions/nestjs-acl-permissions/tsconfig.lib.json",
+        "packageJson": "libs/acl-permissions/nestjs-acl-permissions/package.json",
+        "main": "libs/acl-permissions/nestjs-acl-permissions/src/index.ts",
+        "assets": ["libs/acl-permissions/nestjs-acl-permissions/*.md"]
       }
     },
     "publish": {

libs/acl-permissions/nestjs-acl-permissions/project.json

@@ -1 +1,11 @@
-export * from './lib/nestjs-acl-permissions.module';
+/**
+ * NestJS ACL Permissions Module
+ * CASL-based access control for JSON API controllers
+ */
+
+// Main module
+export { AclPermissionsModule } from './lib/nestjs-acl-permissions.module';
+
+export { AclAction, AclRule, AclRulesLoader, AclSubject } from './lib/types';
+export { ExtendAbility } from './lib/factories';
+export { wrapperJsonApiController } from './lib/wrappers';

libs/acl-permissions/nestjs-acl-permissions/src/index.ts

@@ -1,15 +1,17 @@
-import {
-  Actions,
-  Method,
-  MethodActionMap as MethodActionMapType,
-} from '../types';
+/**
+ * Token for injecting ACL module options
+ */
+export const ACL_MODULE_OPTIONS = Symbol('ACL_MODULE_OPTIONS');
 
-export const IS_PUBLIC_META_KEY = Symbol('IS_PUBLIC_META_KEY');
-export const GET_PERMISSION_RULES = Symbol('GET_PERMISSION_RULES');
+/**
+ * Metadata key for @AclController decorator
+ */
+export const ACL_CONTROLLER_METADATA = Symbol('ACL_CONTROLLER_METADATA');
+/**
+ * Key for storing ACL data in context
+ */
+export const ACL_CONTEXT_KEY = Symbol('ACL_CONTEXT_KEY');
 
-export const MethodActionMap: MethodActionMapType = {
-  [Method.DELETE]: Actions.delete,
-  [Method.GET]: Actions.read,
-  [Method.PATCH]: Actions.update,
-  [Method.POST]: Actions.create,
-};
+
+export const MODULE_REF_PROPS = Symbol('MODULE_REF_PROPS');
+export const ORIGINAL_ORM_SERVICE = Symbol('ORIGINAL_ORM_SERVICE');

libs/acl-permissions/nestjs-acl-permissions/src/lib/constants/index.ts

@@ -0,0 +1,26 @@
+import type { AnyEntity } from '@klerick/json-api-nestjs-shared';
+import type { JsonBaseController } from '@klerick/json-api-nestjs';
+import { UseGuards } from '@nestjs/common';
+import { ACL_CONTROLLER_METADATA } from '../constants';
+import type { AclControllerOptions, AclControllerMetadata, AclControllerMethodsOptions } from '../types';
+
+import { AclGuard } from '../guards';
+
+export function AclController<
+  E extends AnyEntity = AnyEntity,
+  Controller = JsonBaseController<E, 'id'>
+>(options: AclControllerOptions<E, Controller>) {
+  return function <T extends abstract new (...args: any[]) => any>(
+    target: T
+  ): T {
+    const metadata: AclControllerMetadata<E> = {
+      subject: options.subject,
+      methods: (options.methods || {}) as Record<string, AclControllerMethodsOptions>,
+      enabled: options.enabled ?? true,
+    };
+
+    Reflect.defineMetadata(ACL_CONTROLLER_METADATA, metadata, target);
+    UseGuards(AclGuard)(target);
+    return target;
+  };
+}

libs/acl-permissions/nestjs-acl-permissions/src/lib/decorators/acl-controller.decorator.ts

@@ -0,0 +1 @@
+export { AclController } from './acl-controller.decorator';

libs/acl-permissions/nestjs-acl-permissions/src/lib/decorators/index.ts

@@ -0,0 +1,121 @@
+import { ModuleRef } from '@nestjs/core';
+import type { AclContextStore, AclModuleOptions } from '../types';
+import { ExtendAbility } from './ability.factory';
+import { ACL_CONTEXT_KEY, ACL_MODULE_OPTIONS } from '../constants';
+import { FactoryProvider } from '@nestjs/common';
+
+
+/**
+ * Creates a Proxy for ExtendableAbility that lazily retrieves the actual ability
+ * from CLS (Continuation Local Storage) on each method/property access.
+ *
+ * This allows the provider to be a SINGLETON while still accessing request-specific
+ * ability instances without using Scope.REQUEST.
+ *
+ * @param moduleRef - NestJS ModuleRef for lazy dependency resolution
+ * @param options - ACL module options containing contextStore configuration
+ * @returns Proxy that acts as ExtendableAbility
+ */
+export function createAbilityProxy(
+  moduleRef: ModuleRef,
+  options: AclModuleOptions
+): ExtendAbility {
+  let contextStore: AclContextStore | undefined;
+
+  /**
+   * Lazily initializes and retrieves the context store
+   */
+  const getContextStore = (): AclContextStore | undefined => {
+    if (!contextStore && options.contextStore) {
+      contextStore = moduleRef.get(options.contextStore, {
+        strict: false,
+      });
+    }
+    return contextStore;
+  };
+
+  /**
+   * Retrieves ExtendableAbility from CLS for the current request
+   * Throws descriptive error if ability is not found
+   */
+  const getAbility = (): ExtendAbility => {
+    const store = getContextStore();
+    if (!store) {
+      throw new Error(
+        '[ACL] contextStore is not configured. ' +
+          'Make sure you configured AclPermissionsModule.forRoot() with contextStore option. ' +
+          'Example: { contextStore: ClsService }'
+      );
+    }
+
+    const ability = store.get<ExtendAbility>(ACL_CONTEXT_KEY);
+
+    if (!ability) {
+      throw new Error(
+        '[ACL] ExtendAbility not found in context store. ' +
+          'Possible causes:\n' +
+          '  1. Service is called BEFORE AclGuard executed (ability not yet created)\n' +
+          '  2. No rules loaded for this action (check your RulesLoader.loadRules())\n' +
+          '  3. AclGuard was not applied to this controller (check @AclController or wrapperJsonApiController hook)\n' +
+          '  4. contextStore middleware is not mounted (check ClsModule configuration)'
+      );
+    }
+
+    return ability;
+  };
+
+  // Create Proxy that forwards all method/property access to the real ExtendableAbility
+  return new Proxy({} as ExtendAbility, {
+    get(target, prop: string | symbol) {
+      if (!Reflect.has(ExtendAbility.prototype, prop)) {
+        return undefined;
+      }
+
+      // Special handling for Symbol.toStringTag (used by Object.prototype.toString)
+      if (prop === Symbol.toStringTag) {
+        return 'ExtendableAbility';
+      }
+
+      // Special handling for typeof checks
+      if (prop === 'constructor') {
+        return ExtendAbility;
+      }
+
+      // Get the actual ability from CLS
+      const ability = getAbility();
+      // Get the property/method from the real ability
+      const value = Reflect.get(ability, prop, ability);
+
+      // If it's a function, bind it to the ability instance
+      if (typeof value === 'function') {
+        return value.bind(ability);
+      }
+
+      return value;
+    },
+
+    // Support for 'prop in ability' checks
+    has(target, prop) {
+      const ability = getAbility();
+      return Reflect.has(ability, prop);
+    },
+
+    // Support for Object.keys(), Object.getOwnPropertyNames(), etc.
+    ownKeys(target) {
+      const ability = getAbility();
+      return Reflect.ownKeys(ability);
+    },
+
+    // Support for Object.getOwnPropertyDescriptor()
+    getOwnPropertyDescriptor(target, prop) {
+      const ability = getAbility();
+      return Reflect.getOwnPropertyDescriptor(ability, prop);
+    },
+  });
+}
+
+export const AbilityProvider: FactoryProvider<ExtendAbility> = {
+  provide: ExtendAbility,
+  useFactory: createAbilityProxy,
+  inject: [ModuleRef, ACL_MODULE_OPTIONS],
+};