@carlonicora/nextjs-jsonapi 1.78.0 → 1.80.0

package/src/features/rbac/data/RbacService.ts

@@ -1,47 +1,75 @@
 import { AbstractService, EndpointCreator, HttpMethod, Modules } from "../../../core";
-import { FeatureInterface } from "../../feature";
-import { RoleInterface } from "../../role";
-import { PermissionMappingInterface } from "./PermissionMappingInterface";
-import { ModulePathsInterface } from "./ModulePathsInterface";
+import type { RbacMatrixModel } from "./RbacMatrixModel";
+import type { RbacMatrix } from "./RbacTypes";
 
+/**
+ * RbacService — fetches RBAC configuration for the admin UI.
+ *
+ * Declarative-matrix methods (`fetchMatrix`, `saveMatrix`) talk to the
+ * dev-only endpoints added in
+ * `packages/nestjs-neo4jsonapi/.../rbac-dev.controller.ts`. The controller
+ * speaks JSON:API (singleton resource with `type: "rbac-matrix"`, `id:
+ * "singleton"`), so these methods go through the standard `callApi()`
+ * pipeline like every other service in the codebase.
+ *
+ * The backend only registers these routes when `devMode` is enabled on
+ * `RbacModule.register` (see `apps/api/src/features/features.modules.ts`).
+ * In production the routes return 404; callers should guard with a dev-mode
+ * check.
+ */
 export class RbacService extends AbstractService {
-  static async getFeatures(): Promise<FeatureInterface[]> {
-    const endpoint = new EndpointCreator({ endpoint: Modules.Feature }).addAdditionalParam("fetchAll", "true");
+  /**
+   * Fetch the current RBAC matrix plus each module's known BFS relationship
+   * paths (used by the permission picker as scope suggestions).
+   *
+   * Dev-only endpoint — see class header.
+   */
+  static async fetchMatrix(): Promise<{
+    matrix: RbacMatrix;
+    modulePaths: Record<string, readonly string[]>;
+  }> {
+    const endpoint = new EndpointCreator({ endpoint: Modules.RbacMatrix }).generate();
 
-    return this.callApi<FeatureInterface[]>({
-      type: Modules.Feature,
+    const model = await this.callApi<RbacMatrixModel>({
+      type: Modules.RbacMatrix,
       method: HttpMethod.GET,
-      endpoint: endpoint.generate(),
+      endpoint,
     });
-  }
-
-  static async getRoles(): Promise<RoleInterface[]> {
-    const endpoint = new EndpointCreator({ endpoint: Modules.Role }).addAdditionalParam("fetchAll", "true");
 
-    return this.callApi<RoleInterface[]>({
-      type: Modules.Role,
-      method: HttpMethod.GET,
-      endpoint: endpoint.generate(),
-    });
+    return {
+      matrix: model.matrix ?? {},
+      modulePaths: model.modulePaths ?? {},
+    };
   }
 
-  static async getPermissionMappings(): Promise<PermissionMappingInterface[]> {
-    const endpoint = new EndpointCreator({ endpoint: Modules.PermissionMapping });
+  /**
+   * Persist a matrix back to the declarative `permissions.ts` file.
+   *
+   * The backend serializes the matrix to formatted TypeScript using the
+   * provided `roleNames` / `moduleNames` lookup tables (so the emitted file
+   * references `RoleId.X` / `ModuleId.X` rather than raw UUIDs) and writes
+   * it to `outputPath` (absolute, or relative to the repo root).
+   *
+   * Dev-only endpoint — see class header.
+   */
+  static async saveMatrix(args: {
+    matrix: RbacMatrix;
+    roleNames: Record<string, string>;
+    moduleNames: Record<string, string>;
+    outputPath: string;
+  }): Promise<{ bytesWritten: number; path: string }> {
+    const endpoint = new EndpointCreator({ endpoint: Modules.RbacMatrix }).generate();
 
-    return this.callApi<PermissionMappingInterface[]>({
-      type: Modules.PermissionMapping,
-      method: HttpMethod.GET,
-      endpoint: endpoint.generate(),
+    const model = await this.callApi<RbacMatrixModel>({
+      type: Modules.RbacMatrix,
+      method: HttpMethod.PUT,
+      endpoint,
+      input: args,
     });
-  }
-
-  static async getModuleRelationshipPaths(): Promise<ModulePathsInterface[]> {
-    const endpoint = new EndpointCreator({ endpoint: Modules.ModulePaths });
 
-    return this.callApi<ModulePathsInterface[]>({
-      type: Modules.ModulePaths,
-      method: HttpMethod.GET,
-      endpoint: endpoint.generate(),
-    });
+    return {
+      bytesWritten: model.bytesWritten ?? 0,
+      path: model.path ?? "",
+    };
   }
 }

package/src/features/rbac/data/RbacTypes.ts

@@ -13,3 +13,31 @@ export type PermissionsMap = {
   update?: PermissionValue;
   delete?: PermissionValue;
 };
+
+/**
+ * Declarative-RBAC matrix types.
+ *
+ * Mirror of the library types defined in
+ * `packages/nestjs-neo4jsonapi/src/foundations/rbac/dsl/types.ts`.
+ * Frontend does not import from backend, so the shape is redefined here.
+ *
+ * A `PermToken` represents a single permission entry:
+ *  - `scope: true`  → unconditional (e.g. full read of the module)
+ *  - `scope: false` → nothing (rarely used, mostly a placeholder)
+ *  - `scope: "path"` → scoped by relationship path (e.g. "orders.account")
+ */
+export type PermToken = { action: string; scope: boolean | string };
+
+/**
+ * A per-module block of the matrix. Always has a `default` row (permissions
+ * granted to every role). Additional keys are role IDs → role-specific
+ * permission tokens that are unioned with `default` to produce the effective
+ * permissions for that role in that module.
+ */
+export type RbacModuleBlock = { default: PermToken[] } & Record<string, PermToken[]>;
+
+/**
+ * The full RBAC matrix as served by the dev endpoint `GET /_dev/rbac/matrix`.
+ * Keys are module IDs; values are module blocks.
+ */
+export type RbacMatrix = Record<string, RbacModuleBlock>;

package/src/features/rbac/data/index.ts

@@ -3,4 +3,5 @@ export * from "./PermissionMapping";
 export * from "./PermissionMappingInterface";
 export * from "./ModulePaths";
 export * from "./ModulePathsInterface";
+export * from "./RbacMatrixModel";
 export * from "./RbacService";

package/src/features/rbac/index.ts

@@ -1,19 +1,10 @@
 // Data layer
 export * from "./data";
 
-// Hooks
-export { useRbacState } from "./hooks/useRbacState";
-
-// Utils
-export { generateMigrationFile, downloadMigrationFile } from "./utils/RbacMigrationGenerator";
-
 // Components
 export { RbacContainer } from "./components/RbacContainer";
-export { RbacToolbar } from "./components/RbacToolbar";
-export { RbacFeatureSection } from "./components/RbacFeatureSection";
-export { RbacModuleTable } from "./components/RbacModuleTable";
 export { RbacPermissionCell } from "./components/RbacPermissionCell";
 export { RbacPermissionPicker } from "./components/RbacPermissionPicker";
 
 // Module registrations
-export { PermissionMappingModule, ModulePathsModule } from "./rbac.module";
+export { PermissionMappingModule, ModulePathsModule, RbacMatrixModule } from "./rbac.module";

package/src/features/rbac/rbac.module.ts

@@ -1,6 +1,7 @@
 import { ModuleFactory } from "../../permissions";
 import { PermissionMapping } from "./data/PermissionMapping";
 import { ModulePaths } from "./data/ModulePaths";
+import { RbacMatrixModel } from "./data/RbacMatrixModel";
 
 export const PermissionMappingModule = (factory: ModuleFactory) =>
   factory({
@@ -17,3 +18,15 @@ export const ModulePathsModule = (factory: ModuleFactory) =>
     model: ModulePaths,
     moduleId: "f4fb3f01-a947-4c2e-89c8-354a518cdb13",
   });
+
+/**
+ * Dev-only matrix module. The `name` is the URL path of the dev singleton
+ * endpoint (`GET|PUT _dev/rbac/matrix`), NOT a plural resource collection.
+ * This module is only useful when the backend is running with `devMode: true`
+ * on `RbacModule.register`.
+ */
+export const RbacMatrixModule = (factory: ModuleFactory) =>
+  factory({
+    name: "_dev/rbac/matrix",
+    model: RbacMatrixModel,
+  });

package/dist/ModulePathsInterface-BrdqgteS.d.mts

@@ -1,31 +0,0 @@
-import { A as ApiDataInterface } from './ApiDataInterface-BcZeXy5X.mjs';
-
-declare const COMPANY_ADMINISTRATOR_ROLE_ID = "2e1eee00-6cba-4506-9059-ccd24e4ea5b0";
-type PermissionValue = boolean | string;
-type ActionType = "read" | "create" | "update" | "delete";
-declare const ACTION_TYPES: ActionType[];
-/** The permissions object shape used by both Module and PermissionMapping entities */
-type PermissionsMap = {
-    create?: PermissionValue;
-    read?: PermissionValue;
-    update?: PermissionValue;
-    delete?: PermissionValue;
-};
-
-interface PermissionMappingInterface extends ApiDataInterface {
-    get roleId(): string;
-    get moduleId(): string;
-    get permissions(): {
-        create?: boolean | string;
-        read?: boolean | string;
-        update?: boolean | string;
-        delete?: boolean | string;
-    };
-}
-
-interface ModulePathsInterface extends ApiDataInterface {
-    get moduleId(): string;
-    get paths(): string[];
-}
-
-export { type ActionType as A, COMPANY_ADMINISTRATOR_ROLE_ID as C, type ModulePathsInterface as M, type PermissionMappingInterface as P, type PermissionValue as a, type PermissionsMap as b, ACTION_TYPES as c };

package/dist/ModulePathsInterface-DJKs7s_s.d.ts

@@ -1,31 +0,0 @@
-import { A as ApiDataInterface } from './ApiDataInterface-BcZeXy5X.js';
-
-declare const COMPANY_ADMINISTRATOR_ROLE_ID = "2e1eee00-6cba-4506-9059-ccd24e4ea5b0";
-type PermissionValue = boolean | string;
-type ActionType = "read" | "create" | "update" | "delete";
-declare const ACTION_TYPES: ActionType[];
-/** The permissions object shape used by both Module and PermissionMapping entities */
-type PermissionsMap = {
-    create?: PermissionValue;
-    read?: PermissionValue;
-    update?: PermissionValue;
-    delete?: PermissionValue;
-};
-
-interface PermissionMappingInterface extends ApiDataInterface {
-    get roleId(): string;
-    get moduleId(): string;
-    get permissions(): {
-        create?: boolean | string;
-        read?: boolean | string;
-        update?: boolean | string;
-        delete?: boolean | string;
-    };
-}
-
-interface ModulePathsInterface extends ApiDataInterface {
-    get moduleId(): string;
-    get paths(): string[];
-}
-
-export { type ActionType as A, COMPANY_ADMINISTRATOR_ROLE_ID as C, type ModulePathsInterface as M, type PermissionMappingInterface as P, type PermissionValue as a, type PermissionsMap as b, ACTION_TYPES as c };